# Orchestrating agents on the Canvas · OmniGet Docs - URL: https://getomniget.com/docs/canvas-orchestration - Updated: 2026-10-02 - OmniGet 1.0.0 > Free, open-source yt-dlp GUI for Windows, macOS and Linux. Paste a link to save video, audio and files from 1,000+ sites, or run AI coding agents. --- 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**: `⇧⌘L` (macOS) / `Ctrl+Shift+L`, or **Partituras…** in Batuta Search (`⌘K` (macOS) / `Ctrl+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 `⌘L` (macOS) / `Ctrl+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 `⌥⌘→` (macOS) / `Alt+Ctrl+→` and `⌥⌘←` (macOS) / `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](https://getomniget.com/docs/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. `⇧⌘\` (macOS) / `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](https://getomniget.com/docs/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 `⇧⌘L` (macOS) / `Ctrl+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. Warning A partitura can carry startup commands and floor hooks. Read **Commands that will run** before you add a partitura that someone else made. ## 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. `⇧⌘A` (macOS) / `Ctrl+Shift+A` jumps to the next agent that needs you, on any floor or workspace; agents waiting for a permission or stuck come first. `⌥⌘A` (macOS) / `Alt+Ctrl+A` lists every terminal waiting for you. [Omni](https://getomniget.com/docs/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. [Previous**← The Canvas**](https://getomniget.com/docs/canvas) [Next**Canvas shortcuts →**](https://getomniget.com/docs/canvas-shortcuts)