Orchestrating agents

A harness pane with AgentGrid's master MCP can coordinate a team of visible workers. Claude Code, Codex, OpenCode, Cursor, Devin, Grok, and Kimi panes support master orchestration; every installed harness can be selected as a worker.

The master/worker model

A compatible agent pane becomes a master when it starts or associates another pane. Its workers, terminals, and browsers appear below it on the canvas.

The master can list the canvas but cannot read unrelated panes until it explicitly associates them. This canvas-blind default keeps existing notes, terminals, and conversations outside the master's context unless they are needed.

Spawn a role on any harness

spawn_role applies a named role such as builder, qa, validator, or security. spawn_worker starts a raw worker with a prompt. Both return immediately with a paneId.

spawn_role({
  role: "builder",
  name: "Auth refactor",
  harness: "codex",
  model: "gpt-5.6-sol",
  effort: "high",
  prompt: "Refactor the sign-in flow to use the new session helper."
})

• Omit harness to inherit the master's harness.
• Pass harness to choose any installed worker runtime.
• Pass model only when you want to pin a harness-specific model.
• Call list_worker_harnesses for installed choices and current model guidance.
• Pass associatedPaneId when a reviewer belongs visually to a specific builder.

Use a short, descriptive pane name, or rename the selected worker with F2F2. A master can also rename a pane it owns.

Model effort

effort is an optional soft model-behavior control and requires an explicit harness. It can influence reasoning, response detail, tool use, latency, and token consumption, but it is not an exact token cap or guaranteed budget.

AgentGrid validates cataloged models against the levels they advertise. Codex and Claude use native categorical controls, OpenCode maps effort to --variant, Antigravity to --effort, Grok to --reasoning-effort, and Pi to --thinking. Devin effort tiers are represented by supported model ids. Kimi has no compatible effort control in headless prompt mode.

Cursor Auto launches successfully but returns an effortWarning because the requested category cannot be forwarded independently. Other unsupported or ambiguous combinations fail before a pane is created. Omitting effort sends no effort argument, leaving the harness's native or last-selected behavior intact.

Wait, inspect, and reuse

Because spawns are non-blocking, the master waits separately:

• wait_for_worker waits for one worker's current turn.
• wait_for_any returns the first completed worker from a set; call it repeatedly until every parallel worker reports.
• read_worker_output inspects progress without stopping the turn.
• send_to_worker gives an existing worker a follow-up while preserving its context.

Reuse a worker for corrections and repeat review rounds when it already has the right role and context. Spawn a new peer when the work is genuinely independent or a different harness perspective is useful.

A production review loop

1. Spawn a builder and wait for its implementation and checks.
2. Fan out QA, validation, and security roles. Different harnesses or models can review the same diff independently.
3. Wait for every reviewer and consolidate actionable findings.
4. Send the findings back to the same builder.
5. Reuse the same reviewers against the new revision until each gives a shipping verdict.

Workers with terminal access can start their own visible test runners and dev servers. Those terminals belong to the worker and close with it.

Recover after restart

Use list_my_team to rediscover the master's visible workers, terminals, and browsers after resume. Each result includes a title and summary to help match it to the original task.

For sessions no longer represented by a pane, use list_recoverable_sessions, then resume_worker with the returned sessionId and harness.

Related

• Agents and workers - the underlying concepts and session behavior.
• Coding harnesses - master and worker capabilities by harness.
• Roles - built-in roles and project-defined roles.
• MCP and integrations - the complete orchestration tool surface.