Skip to main content
Claude Code supports multi-agent execution through a layered system: a main agent can spawn sub-agents in one of four modes, agents can communicate via a shared task board and message-passing tools, and an optional swarm mode (feature-gated) enables autonomous task claiming.

​
Architecture Diagram

                    MAIN AGENT
                    ==========
                        │
        ┌───────────────┼───────────────┐
        ▼               ▼               ▼
 ┌──────────────┐ ┌──────────┐ ┌──────────────┐
 │  FORK AGENT  │ │ REMOTE   │ │ IN-PROCESS   │
 │              │ │ AGENT    │ │ TEAMMATE     │
 │ Fork process │ │ Bridge   │ │ Same process │
 │ Shared cache │ │ session  │ │ Async context│
 │ Fresh msgs[] │ │ Isolated │ │ Shared state │
 └──────────────┘ └──────────┘ └──────────────┘

COMMUNICATION:
├─ SendMessageTool     → agent-to-agent messages
├─ TaskCreate/Update   → shared task board
└─ TeamCreate/Delete   → team lifecycle management

SWARM MODE (feature-gated: COORDINATOR_MODE):
┌─────────────────────────────────────────────┐
│  Lead Agent                                 │
│    ├── Teammate A ──> claims Task 1         │
│    ├── Teammate B ──> claims Task 2         │
│    └── Teammate C ──> claims Task 3         │
│                                             │
│  Shared: task board, message inbox          │
│  Isolated: messages[], file cache, cwd      │
└─────────────────────────────────────────────┘

​
Spawn Modes

The agent runs in the same process as the parent. State is shared via AsyncLocalStorage context isolation. This is the lowest-overhead spawn mode — no process fork, no worktree creation.
Main Process
└── AsyncLocalStorage context A  (main agent)
└── AsyncLocalStorage context B  (sub-agent, in-process)
Use this for lightweight sub-tasks that do not need file isolation.

​
Spawning a Sub-Agent with AgentTool

1

Main agent calls AgentTool

The main agent invokes AgentTool with a task description and the desired spawn mode. AgentTool is registered in the tool dispatch map and implements the standard Tool<Input, Output, Progress> interface.
2

AgentTool creates a Task record

A new Task with a prefixed ID (e.g., a_<8chars> for agent tasks) is created and persisted. Task IDs encode their type: b=bash, a=agent, r=remote, t=team.
3

Sub-agent starts with fresh messages[]

For fork/worktree modes, the child process starts with an empty messages[]. The task description becomes the first user message. The child has its own QueryEngine instance.
4

Results flow back to parent

The sub-agent’s output is collected and returned as a tool_result block in the parent’s messages[]. The parent agent continues its loop with the sub-agent’s result available.

​
Agent Communication

​
SendMessageTool

SendMessageTool provides request-response messaging between agents. One agent sends a message to another agent’s inbox by task ID; the recipient polls for new messages in its idle cycle. 
Agent A                           Agent B
  │                                  │
  ├── SendMessageTool(to: b_xyz)     │
  │        │                         │
  │        └──> writes to inbox ──> │
  │                                  ├── reads message
  │                                  ├── processes request
  │                                  └── SendMessageTool(to: a_abc, reply)
  │                                         │
  └─────────────────────────────────────────┘

​
TaskCreate / TaskUpdate / TaskGet / TaskList

Agents share a file-based task board. Any agent can create tasks, claim them, update their status, and list all open work.
ToolDescription
TaskCreateToolCreates a new task with description, priority, and optional dependencies
TaskUpdateToolUpdates status (open, in_progress, done, blocked)
TaskGetToolRetrieves a single task by ID
TaskListToolLists all tasks, optionally filtered by status or assignee
TaskStopToolCancels a running task
TaskOutputToolReads streamed output from a background task

​
TeamCreate / TeamDelete

TeamCreateTool spawns a set of named teammates as InProcessTeammateTask instances. Each teammate gets an async mailbox and runs concurrently in the same process. TeamDeleteTool shuts down the team and cleans up resources.

​
Coordinator Mode (Swarm)

Coordinator mode is controlled by the COORDINATOR_MODE feature flag. This module (coordinator/workerAgent.js) is not included in the published npm package — it exists only in Anthropic’s internal monorepo.
When enabled, coordinatorMode.ts gives each teammate an idle cycle: when a teammate has no active work, it automatically scans the shared task board and claims the highest-priority unclaimed task. This eliminates the need for a lead agent to manually assign work. 
Idle Teammate
      │
      ▼
poll TaskList(status: 'open')
      │
  tasks found?
      │
   ┌──┴──┐
  yes    no
   │      │
   ▼      └── sleep(pollIntervalMs)
TaskUpdate(claim: self)        │
   │                           └──> loop
   ▼
executeTask()
The coordinator context is injected via getCoordinatorUserContext() from QueryEngine.ts:115-117: 
const getCoordinatorUserContext: (
  mcpClients: ReadonlyArray<{ name: string }>,
  scratchpadDir?: string,
) => { [k: string]: string } = feature('COORDINATOR_MODE')
  ? require('./coordinator/coordinatorMode.js').getCoordinatorUserContext
  : () => ({})

​
Worktree Isolation (s12)

EnterWorktreeTool creates a new git worktree for the calling agent and changes its cwd to the new directory. ExitWorktreeTool removes the worktree and restores the original cwd. Worktrees are bound to task IDs so cleanup is deterministic even if the agent crashes. 
EnterWorktreeTool(taskId: "a_abc123")
      │
      ▼
git worktree add .worktrees/a_abc123
      │
      ▼
setCwd(.worktrees/a_abc123)
      │
   [agent works in isolation]
      │
ExitWorktreeTool(taskId: "a_abc123")
      │
      ▼
git worktree remove .worktrees/a_abc123
      │
      ▼
restoreCwd(original)
The worktree utilities live in src/utils/worktree.ts and are called from bridgeMain.ts (createAgentWorktree, removeAgentWorktree).

Build docs developers (and LLMs) love

Get started for freeTalk to us