Claude Code Multi-Agent Runtime: Coordinator, Three Backends, Disjoint Ownership

Running multiple agents concurrently is a coordination problem, not just a spawning problem.

Claude Code has three swarm backends, a coordinator mode, and a team context system. Each part solves a distinct piece of the multi-agent problem.

File structure

src/
├── coordinator/
│   └── coordinatorMode.ts
└── utils/
    ├── swarm/
    │   ├── backends/
    │   │   ├── TmuxBackend.ts
    │   │   ├── ITermBackend.ts
    │   │   └── InProcessBackend.ts
    │   └── teamContext.ts

How the coordinator pattern works

Three backends, one interface

The SwarmBackend abstraction is one of the cleaner designs in the codebase.

The coordinator never calls tmux new-window or AppleScript directly. It calls backend.spawn(task) and backend.getResult(id).

The backend selection happens once at session start, based on environment detection:

1. check for tmux socket → TmuxBackend
2. check TERM_PROGRAM for iTerm2 → ITermBackend
3. fallback → InProcessBackend

This means the same multi-agent workflow works in a developer's local terminal (visible panes), in macOS iTerm2 (native splits), and in a CI environment (in-process, no panes).

The tradeoff is that InProcessBackend loses the observability of visible panes. The coordinator can still see subagent results through the task channel, but the user cannot watch subagents working in real time.

Why "synthesize first" is the right coordinator strategy

An alternative coordinator strategy is "spawn then plan" — spawn subagents speculatively and let them explore, then synthesize based on what they found.

Claude Code explicitly rejects this in the coordinator system prompt.

The reason: uncoordinated exploration produces file conflicts.

If two subagents both decide to refactor a shared utility file without coordination, their changes will conflict. The coordinator's planning step must assign disjoint file ownership before any spawning happens.

"Synthesize first" means:

1. understand the full task before splitting it
2. assign disjoint ownership explicitly
3. spawn subagents with complete instructions
4. collect and synthesize results

This is slower to start (planning takes time before any subagent begins work) but produces fewer conflicts and more predictable output.

Team context in AppState

AppState includes a team context field that tracks which subagents are active, their assigned tasks, and their current status.

This is the coordination state for the coordinator turn — it knows who is working on what.

The UI can surface this as a "team" view showing active subagents and their status, even when using InProcessBackend where there are no visible panes.

// The interface all backends implement
interface SwarmBackend {
spawn(task: SubagentTask): Promise<SubagentHandle>
getResult(id: string): Promise<SubagentResult>
stop(id: string): Promise<void>
}

interface SubagentTask {
id: string
instructions: string
fileOwnership: string[]  // disjoint file set assigned by coordinator
context: SessionContext
}

// TmuxBackend: each subagent gets a pane in a binary tree layout
class TmuxBackend implements SwarmBackend {
async spawn(task: SubagentTask): Promise<SubagentHandle> {
  const paneId = await this.createPane(buildBinaryTreeLayout(this.activeCount))
  await this.runInPane(paneId, `claude --task "${task.id}"`)
  return { id: task.id, paneId }
}
}

// InProcessBackend: subagent runs as async task
class InProcessBackend implements SwarmBackend {
private tasks = new Map<string, Promise<SubagentResult>>()

async spawn(task: SubagentTask): Promise<SubagentHandle> {
  const result = runAgentInProcess(task)
  this.tasks.set(task.id, result)
  return { id: task.id }
}

async getResult(id: string): Promise<SubagentResult> {
  return this.tasks.get(id)!
}
}

// Coordinator turn: plan → spawn → collect → synthesize
async function runCoordinatorTurn(
task: string,
backend: SwarmBackend
): Promise<string> {
// 1. Plan with coordinator system prompt (synthesize first)
const plan = await planWithCoordinator(task)

// 2. Spawn subagents with disjoint task assignments
const handles = await Promise.all(
  plan.subtasks.map(t => backend.spawn(t))
)

// 3. Collect results
const results = await Promise.all(
  handles.map(h => backend.getResult(h.id))
)

// 4. Synthesize
return synthesizeResults(results, plan)
}