Orchestrating agents

A Claude pane becomes an orchestrator the moment it spawns its first worker — from there it's your hands on a small team of agents running side-by-side on the canvas.

The master/worker model

Every Claude pane is master-capable by default. It only becomes a "master" once it calls an MCP tool that spawns or associates panes. From that point on it owns a set of child panes — Agent Grid workers, MCP-spawned terminals, and observable browsers — that live below it on the canvas.

The master is blind to the canvas until it opts in. It cannot see other panes — your notes, your other Claude sessions, the browser you have open — until it explicitly calls associate_pane for a specific pane. Listing panes is fine; reading their contents requires the association first.

See Agents and workers for the underlying mental model.

The eight built-in roles

A role is a named bundle of systemPrompt, allowed/disallowed tools, default model, MCP servers, browser access, and backend (PTY vs SDK). Agent Grid ships eight:

For the full role table and the custom-role schema, see Reference → Roles.

Spawning workers

Two tools spawn workers, both non-blocking — they return immediately with a paneId while the worker's first turn runs in the background.

• spawn_role — spawn from a named role (builder, qa, validator, backend, frontend, devops, security, browser_qa, or any custom role). The role decides the system prompt, the tool restrictions, and the backend.
• spawn_worker — spawn a raw worker without a role; you pass the prompt and optional withBrowser.

Both accept a short name for the pane title so multiple parallel workers stay distinguishable on the canvas. If you omit it, one is derived from the first sentence of the prompt.

spawn_role({
  role: "builder",
  name: "Auth refactor",
  prompt: "Refactor the sign-in flow to use the new session helper. See docs/auth-system-plan.md."
})

Pass associatedPaneId when you're spawning a reviewer of a specific builder — the new pane's connector anchors to that builder instead of to the master, which keeps the canvas readable.

Waiting on workers

Spawns return instantly, so blocking is a separate step:

• wait_for_worker(paneId, timeoutMs?) — block until that worker's current turn finishes. Returns immediately if the worker is already idle.
• wait_for_any(paneIds, timeoutMs?) — race a list of workers; return the first one that finishes, with its response. Call it again with the remaining ids to harvest the next completion.

Use wait_for_any whenever you fan out — you want to react to whichever reviewer comes back first, not wait sequentially on each. Use read_worker_output(paneId) mid-flight to peek at progress without blocking.

Workers can open their own terminals

A worker whose role has terminal access — builder, backend, frontend, and devops — can open visible terminal panes on the canvas itself, not just the master. Each of these workers gets its own terminal MCP server exposing the same spawn_terminal tools the master has, scoped to that worker's pane. The terminals are parented to the worker and auto-close when its pane does — handy for a builder that needs to run a dev server or watch a test suite while it works.

The builder → QA → fix → validator loop

The canonical review-loop pattern is three parallel reviewers against a single builder, then a fix round:

1. Spawn the builder. spawn_role({ role: "builder", name: "<feature>", prompt: "<spec>" }). Wait for it.
2. Fan out reviewers in parallel. spawn_role({ role: "qa", associatedPaneId: builderPaneId, prompt: "Review the diff." }) — and the same for validator and (if relevant) security. The associatedPaneId ties each reviewer's connector to the builder.
3. Wait for all reviewers. wait_for_any([...]) repeatedly until each has reported.
4. On NEEDS CHANGES — forward the consolidated findings verbatim to the builder via send_to_worker(builderPaneId, feedback). Don't paraphrase; the file:line citations matter for fix accuracy.
5. On a new builder commit — re-spawn the same reviewers against the new HEAD. Loop until each returns SHIP IT.

This is the standing review loop the project uses internally; it's described from the orchestrator's side in the repo's CLAUDE.md.

After --resume: finding your team

When a master comes back from --resume, its in-memory worker list is gone — but the canvas still has all the panes it spawned. Call list_my_team to re-discover them. Each entry carries a title and a one-line summary (the worker's first prompt, a terminal's initialCommand, or a browser's URL) so you can match panes back to your intent without re-spawning.

For orphan worker sessions that aren't on the canvas anymore, use list_recoverable_sessions to find them by sessionId, then resume_worker to re-attach.

Related

• Working with Claude, Codex, and Antigravity — what each provider pane is and how to authenticate.
• MCP and integrations — the master's full tool surface.
• Reference → Roles — every built-in role plus the .agent-grid/roles.json schema.