Coordinator Mode

Claude Code has two distinct multi-agent systems. Coordinator Mode is a hub-and-spoke model where a central agent orchestrates workers. Team/Swarm is peer-to-peer where any teammate can message any other.

2 multi-agent topologies 4 coordinator-only tools 3 terminal backends 1s mailbox polling interval

i Two different systems, not one

Coordinator Mode is activated with an env var and restricts the main model to orchestration-only tools. Team/Swarm is activated by passing a team_name to the Agent tool and uses tmux for visual layout and file-based mailboxes for messaging.

Topologies

Coordinator Mode (hub-and-spoke)

Coordinator

(Agent, SendMessage, TaskStop only)

┌────┼────┐

Worker 1 Worker 2 Worker 3

(full tools) (full tools) (full tools)

Activated with CLAUDE_CODE_COORDINATOR_MODE=1. Coordinator cannot touch the filesystem directly.

Team/Swarm (peer-to-peer)

Team Lead Teammate A

<── SendMessage ──>

└────────┬────────┘

Teammate B

Activated by passing team_name to the Agent tool. Visualized in tmux split panes.

Coordinator Mode

Activation

Requires feature flag COORDINATOR_MODE enabled in the build, plus the environment variable:

CLAUDE_CODE_COORDINATOR_MODE=1

What changes

Aspect	Normal mode	Coordinator mode
System prompt	Default Claude Code prompt	Coordinator-specific prompt
Available tools	All ~45 tools	Agent, SendMessage, TaskStop, SyntheticOutput only
File access	Direct (Read, Edit, Write)	Only through workers
Shell access	Direct (Bash)	Only through workers

4-phase task workflow

Phase	Who	Purpose
1. Research	Workers (parallel)	Investigate the codebase — run freely in parallel
2. Synthesis	Coordinator	Read findings, write specs with exact file paths and line numbers
3. Implementation	Workers (sequential per file set)	Make changes per spec — one worker at a time per file area
4. Verification	Workers	Test that it works — can run alongside impl in different file areas

Worker result format

Worker results arrive back as user-role messages with XML:

<task-notification>
  <task-id>agent-a1b2c3</task-id>
  <status>completed</status>  <!-- completed | failed | killed -->
  <summary>Brief summary of what happened</summary>
  <result>Detailed output from the worker</result>
  <usage>Token usage stats</usage>
</task-notification>

Continue vs. spawn decision

Situation	Action	Reason
Research worker explored files that need editing	Continue (SendMessage)	Already has context loaded
Research was broad but implementation is narrow	Spawn fresh	Don't carry unnecessary context
Fixing a failure	Continue	Has error context
Verifying another worker's code	Spawn fresh	Fresh eyes, no bias
Previous approach was completely wrong	Spawn fresh	Clean slate

i Critical rule: workers cannot see the coordinator's conversation

Every worker prompt must be completely self-contained. The coordinator must synthesize findings and include file paths, line numbers, and exact instructions. Never write "based on your findings" — the worker has no access to prior context.

Team/Swarm system

Team structure

Team config

~/.claude/teams/{team-name}/config.json

Task list

~/.claude/tasks/{team-name}/

Inboxes

~/.claude/teams/{team-name}/inboxes/{name}.json

Team lead name

"team-lead" (fixed)

Team workflow

Team lead creates team with TeamCreate

Create tasks with Task tools

Spawn teammates with Agent tool (team_name + name parameters)

Assign tasks with TaskUpdate (owner field)

Teammates work and mark tasks completed

Teammates communicate via SendMessage

Graceful shutdown: SendMessage with {type: "shutdown_request"}

Clean up with TeamDelete (only works when no teammates are active)

Teammate types

In-process

Uses AsyncLocalStorage for isolated context within the same process. Used for testing and headless mode.

Tmux

Runs as a separate Claude Code process in a tmux pane. Each pane has a unique border color and title.

iTerm2

Alternative backend for iTerm2 on macOS, using AppleScript for tab/split management.

Tmux layout

Inside existing tmux session

Splits the current window
Team lead: 30% left panel
Teammates: 70% right panel
Layout: main-vertical

Outside tmux

Creates new session: claude-swarm
Window name: swarm-view
Isolated socket: claude-swarm-{pid}
Layout: tiled

SendMessage tool

Dual-purpose tool: continues existing workers in Coordinator Mode, and routes messages between teammates in Team/Swarm mode.

In Coordinator Mode

// Continue an existing worker by agent ID
SendMessage({
  to: "agent-a1b2c3",
  message: "Fix the bug in auth.ts:45 based on..."
})
// Worker resumes with full context preserved

In Team/Swarm Mode

// Direct message to a teammate
SendMessage({ to: "backend-dev", message: "..." })

// Broadcast to all teammates (use sparingly)
SendMessage({ to: "*", message: "All tests pass" })

Message routing logic

bridge:<id>

Remote session via REPL bridge

uds:<path>

Local peer via Unix Domain Socket

Registered agent ID

Enqueue or resume the agent in-process

"*"

Broadcast to all teammates via file mailbox

Teammate name

Write to teammate's file mailbox

Structured message types

Type	Purpose
shutdown_request	Request teammate to stop gracefully
shutdown_response	Acknowledge shutdown
plan_approval_response	Respond to plan mode approval request

Mailbox system

File-based messaging using JSON files with proper-lockfile to prevent race conditions when multiple teammates write to the same inbox simultaneously. Polled every 1 second by the useInboxPoller React hook.

Message format

{
  from: string,       // Sender name
  text: string,       // Message content
  timestamp: number,  // Unix timestamp
  read: boolean,      // Read status
  color?: string,     // Sender's color (for UI)
  summary?: string    // Brief summary
}

Messages are injected into the teammate's context as XML:

<teammate-message teammate_id="frontend-dev" color="blue" summary="Found the CSS bug">
The issue is in src/styles/main.css line 42. The flex-direction
property is set to "column" but should be "row" for the header layout.
</teammate-message>

The inbox poller also handles: permission requests/responses, sandbox permissions, shutdown requests, team permission updates, mode set requests, and plan approval requests.

Coordinator Mode vs Team/Swarm

Aspect	Coordinator Mode	Team/Swarm
Topology	Hub-and-spoke	Peer-to-peer
Communication	Coordinator ↔ Workers only	Any teammate ↔ Any teammate
Coordinator tools	Agent, SendMessage, TaskStop only	Full toolset
Worker tools	Full toolset (no Agent/SendMessage)	Full toolset + SendMessage
Messaging	task-notification XML	File-based mailboxes (JSON)
Terminal UI	No special UI	Tmux split panes
Activation	CLAUDE_CODE_COORDINATOR_MODE=1	Agent tool with team_name param
Best for	Complex tasks needing strict orchestration	Collaborative parallel work

→ The key constraint that makes Coordinator Mode safe

The coordinator has zero filesystem access. It cannot read, write, or run commands. Every action on the codebase must go through a worker. This means the coordinator is purely a reasoning and delegation layer — it can plan and orchestrate without accidentally making changes itself.