Agents and workers

Agent Grid distinguishes the master (or orchestrator) — a Claude pane that drives other agents — from the workers it spawns. The vocabulary matters because the surface area each one has is different.

Master and worker

• A master is a Claude pane that calls MCP tools to spawn or coordinate other panes. Every Claude pane is master-capable from the moment it spawns — there is no separate "master" pane type. A pane becomes the master the first time it invokes an MCP tool that spawns or associates panes.
• A worker is a Claude Code or Codex agent the master spawns. Workers appear on the canvas as claude_worker or codex_worker panes. They aren't on the spawn menu; only a master (or you, via a role spawn) puts them there.

The shared canvas is the only place the two meet visually. The master can ask MCP for the worker's output, send it messages, wait for it, and eventually kill or close it.

The master is canvas-blind by default

Newly spawned masters cannot see any panes on the canvas. The MCP read_pane tool only returns content from panes the master has explicitly associated itself with.

To bring a pane into the master's field of view, the master calls:

associate_pane({ pane_id })

After that, read_pane, read_terminal_output, and the rest of the read tools return that pane's content. The opt-in is deliberate: the master only sees what you (or it) point it at, never the whole canvas implicitly.

Sessions and resume

Each Claude pane carries a sessionId that maps to the claude --resume history for the space's project folder. That means you can close a Claude pane (or the whole app) and pick the conversation up later.

To resume:

1. Open the spawn menu (Cmd+NCtrl+N).
2. Pick Resume Claude under Sessions.
3. Choose a session from the list — they're filtered to the active space's project folder.

A resumed Claude pane is just a Claude pane. It's still master-capable, can still spawn workers, and still owns its own sessionId. There's no "as worker" or "as master" choice — every Claude pane is the same shape.

Workers carry an analogous workerSessionId, and the master can list and resume recoverable worker sessions through the MCP list_recoverable_sessions and resume_worker tools.

PTY vs SDK backends

A worker runs through one of two backends.

• PTY — a headless claude CLI session driven through a terminal. This is the same path the visible Claude panes use, so PTY workers route to your Max subscription quota.
• SDK — the Claude Agent SDK called programmatically. This is the standard path; it does not consume the Max quota.

The pane choice is per-role and per-spawn. Some roles are pinned to SDK because they need MCP servers (like Playwright for visual QA) that the PTY backend cannot wire in. See Roles for the per-role defaults and Orchestrating agents for picking a backend at spawn time.

Next

• Panes — the canvas surface every agent runs in.
• The .agent-grid folder — where custom roles for workers live.