Our GitHub account is temporarily unavailable: links to the code, releases and issues will not open.

Report a bug or talk to us

Canvas

Orchestrating agents on the Canvas

The Canvas can do more than hold terminals side by side: agents tied by cords talk to each other, one agent can lead the others as the Maestro, and floors keep parallel work on separate branches. Routines send prompts on a schedule, and partituras save a whole team so you can set it up again in one step.

Where it is

Everything on this page lives on the Canvas in the sidebar:

  • Maestro Mode: the baton button in a terminal’s header.
  • Roles… and New routine…: right-click a terminal.
  • Floors: the layers button in the floor bar.
  • Partituras: ⇧⌘LCtrl+Shift+L, or Partituras… in Batuta Search (⌘KCtrl+K).

Cords between agents

A cord lets the agents at its two ends reach each other. The cord lights up while a message is in flight.

  1. Select two terminals and press ⌘LCtrl+L, or pick the Connect tool and drag from one to the other.
  2. Click the cord to select it, then pick its label: ask, message, handoff or spawn.
  3. With a handoff cord, when the agent at the start finishes its turn, its result goes to the agent at the end.

To walk along the cords of the selected node, press ⌥⌘→Alt+Ctrl+→ and ⌥⌘←Alt+Ctrl+←. A cord to a node on another floor or workspace shows up as a Connector chip; Go to the other end jumps there.

Maestro Mode

The Maestro is an agent that leads the others. In Maestro Mode, the agent in that terminal can recruit new agents, give them roles, connect and disconnect cords, swap a terminal’s agent, dismiss agents, and create floors, workspaces and routines for you.

  1. In a terminal’s header, click the baton button (Turn on Maestro Mode). The header now shows Maestro.
  2. Ask the agent in that terminal to build the team, for example “recruit a reviewer and a tester for this task”.
  3. Click Maestro again to turn it off.

An agent that tries these actions without Maestro Mode gets “This terminal is not the Maestro. Turn on Maestro Mode on it first.” To make every terminal from an agent preset start as the Maestro, tick Maestro (can recruit and manage other agents) in the preset (Canvas settings).

Roles

A role is a set of instructions a terminal starts with: what the agent focuses on, who it talks to and what done means.

  1. Right-click a terminal and choose Role….
  2. Pick a role from Choose a role, or No role. Manage roles… opens the Roles library.
  3. In the library, New role asks for a Role name, One line: what this role is for, the Instructions, a Default agent, an Icon, a Color and where it is Available in: the Library (every workspace) or This workspace.
  4. Discover roles in the project finds role.json files in .omniget/roles of the workspace folder. Import or Import all brings them in.

Changing a role’s instructions restarts the terminals that use it.

Floors

A floor is a separate board inside one workspace. Each workspace starts on the Ground. A new floor is a Git worktree on its own branch, a Copy-on-write clone, or Shares the ground folder, so agents can try work in parallel without touching the ground’s files until you land it.

Create a floor

  1. Click the layers button in the floor bar, then New floor.
  2. Type a Name. The Branch is made from the name unless you type one; tick Use an existing branch to reuse one.
  3. Tick No git isolation (share the ground folder) to skip the branch, and Clone the ground layout to copy the ground’s nodes.
  4. Click Create. The bar shows the progress (branching, cloning, copying layout, running setup).

The floor chips show ↑ with the commits ahead and ● with the uncommitted files. ⇧⌘\Ctrl+Shift+\ opens the floors overview for the workspace: terminals, how many are working, how many need you, commits ahead and changed files.

Land a floor

  1. Go to the floor and click Land. (A floor that shares the ground folder has nothing to land.)
  2. Check the summary of commits and files, and any Conflicts.
  3. Choose where it goes (Into), edit the Merge message, and tick Keep the floor after landing or Delete the floor branch.
  4. Click Land.

To throw a floor away, click the delete button, choose Keep the branch if you want it, tick Delete even with uncommitted changes if needed, and click Delete floor. Teardown hooks run first.

Hooks and environment

  • Hooks run commands on each floor: Setup commands when a floor is made (with Run setup when a floor is created) and Teardown commands before it goes away. Commands can use the variables $OMNIGET_FLOOR_NAME, $OMNIGET_BRANCH_NAME, $OMNIGET_FLOOR_PATH, $OMNIGET_ROOT_PATH, $OMNIGET_PROJECT_NAME, $OMNIGET_FLOOR_PORT and $PORT.
  • Environment (Floor hooks and environment) sets where the floor’s terminals run: This computer, This computer (tmux, persistent), SSH, Docker, Docker Sandbox, Custom runtime or WSL. Test checks the connection. Turn kinds on or off in Canvas settings.

Routines

A routine sends a prompt to a terminal once or on a schedule, or reminds you of something.

  1. Right-click a terminal and choose New routine…, or run Routines… in Batuta Search.
  2. Give it a Name and pick the Terminal, or None (reminder only) for a reminder.
  3. Write the Prompt. To send several steps one after the other, put a line with && between them.
  4. Under When, pick Once, Every… (in seconds, minutes or hours), Every day or Every week. The shortest interval is 10 seconds.
  5. Under Ends, pick Never, After a number of runs or On a date.
  6. Open Pre-run script and options for a Pre-run script (the routine runs only if it exits successfully, and its output can fill {{output}} in the prompt), Skip if the terminal is busy and Notify me when it runs.
  7. Click Save.

The Routines list shows the next run of each routine. Pause and Resume, Run now, Delete and History work on one routine; Every run in this workspace shows the full history. Routines made by an agent are marked made by an agent.

Partituras

A partitura is a saved team: the selected terminals, notes and portals with their roles, cords, startup commands, floor hooks, budget and permissions. Add it to any canvas to set the same team up again.

Save one

  1. Select the nodes to keep.
  2. Run New Partitura from Selection in Batuta Search, or open Partituras and click New partitura from selection.
  3. Fill in Name, Description and Scope (This workspace or Global).
  4. Choose what goes in: Include startup commands, Send notes blank, Include chat history, and under Hooks, budget and permissions the Max spend and Permission mode.
  5. Click Save. Update Partitura from Selection… replaces an existing one and keeps its name.

Use one

  1. Press ⇧⌘LCtrl+Shift+L and find the partitura with Search by name, role or workspace.
  2. Click Add to canvas, or drag it onto the canvas.
  3. In Review partitura, check the Commands that will run, the Roles (new, same as yours, or different from yours: Keep mine, Use theirs or Keep both), the Portals, the floor hooks and the Budget and permissions.
  4. Click Add to canvas.

Import… and Export all… move partituras between computers. Commands are reviewed when you add a partitura to a canvas.

Who needs you

When an agent waits for you, its header shows Needs you and, with Notify when an agent needs attention on, you get a notification. ⇧⌘ACtrl+Shift+A jumps to the next agent that needs you, on any floor or workspace; agents waiting for a permission or stuck come first. ⌥⌘AAlt+Ctrl+A lists every terminal waiting for you. Omni can also tell you when an agent is done, stuck or failed.

Common problems

“This terminal is not the Maestro”

Turn on Maestro Mode on the terminal that should lead, with the baton button in its header.

“Nothing to land: the target already has these commits.”

The floor has no commits the target branch lacks. Commit the floor’s changes first.

A routine says “skipped: terminal busy”

Skip if the terminal is busy is on and the agent was working. Turn it off, or pick a quieter time.