Home › Concepts › Multi-Agent Patterns

Multi-Agent Patterns

Four orchestration patterns for running multiple agents in Claude Code — from lightweight forks sharing a prompt cache to fully coordinated worker teams.

Pattern 1: Fork subagent (cache-sharing)

The cheapest multi-agent pattern. A fork agent inherits the parent's exact system prompt and tool array, making the API request prefix byte-identical. This means the child gets prompt cache hits from the parent's cached prefix.

How it works: - buildForkedMessages() clones the parent's assistant messages + placeholders + directive - useExactTools: true ensures identical tool registration - Child runs with maxTurns: 1 (single turn) or more for complex tasks - Result returned to parent as tool_result

When to use: Quick research questions, validation checks, memory extraction. The cache sharing makes forks nearly free in terms of prompt cache cost.

Limitation: Fork and coordinator modes are mutually exclusive per session.

Pattern 2: Background async agents

The standard run_in_background: true pattern. The parent spawns an agent that executes independently, returning immediately with an agentId. The agent runs in the same process but with isolated context via AsyncLocalStorage.

How it works: - registerAsyncAgent() creates a LocalAgentTask in AppState - runWithAgentContext() wraps execution for analytics isolation - Agent completes → enqueueAgentNotification() → XML <task-notification> delivered to parent - Parent receives notification as a user message and synthesizes the result

Isolation guarantees: - readFileState — cloned (separate file cache) - abortController — new linked controller (parent abort propagates down, not up) - setAppState — no-op (agents can't modify parent state) - setAppStateForTasks — always goes through (agents must register tasks)

When to use: Independent research tasks, parallel file analysis, any work that doesn't need to share state.

Pattern 3: Worktree-isolated agents

Agents spawned with isolation: "worktree" get their own git worktree — a separate checkout of the same repo. This provides filesystem isolation: the agent can modify files without affecting the parent's working directory.

How it works: - Claude Code creates a temporary git worktree branch - Agent's cwd is set to the worktree path - After completion, if the agent made changes, the worktree path and branch are returned - If no changes, the worktree is automatically cleaned up

When to use: Parallel PoCs (throwaway prototypes), risky refactors, any work where you want to modify code without affecting the main checkout.

Pattern 4: Coordinator mode (full orchestration)

The most powerful pattern. Transforms Claude Code into a multi-agent orchestrator with a completely different system prompt.

How it works: - Coordinator receives a custom prompt defining a research → synthesis → implementation → verification workflow - Workers are always spawned async (forced by coordinator mode) - Workers can't see the conversation — every prompt must be self-contained - Workers report back via XML task notifications - Coordinator synthesizes findings and crafts precise implementation specs - Scratchpad directory enables durable cross-worker knowledge sharing

Coordinator's unique rules: - Owns synthesis — never delegates understanding ("based on your findings" is an anti-pattern) - Workers receive precise specs with file paths, line numbers, exact changes - Choose continue vs. spawn based on context overlap - Four-phase workflow: research → synthesis → implementation → verification

Worker tool restrictions: - Full tool set minus coordinator-internal tools (TeamCreate, TeamDelete, SendMessage, SyntheticOutput) - In simple mode: only Bash, Read, Edit

When to use: Complex multi-file changes, tasks requiring parallel investigation followed by coordinated implementation.

Pattern comparison

Aspect Fork Async agent Worktree Coordinator
Cache sharing Full prompt cache reuse No special sharing No No
Isolation Context only Context + state Context + filesystem Context + state + async
Parallelism Sequential (single turn) Parallel (background) Parallel (background) Parallel (managed workers)
Communication Direct return Task notification Task notification Task notification + SendMessage
Synthesis Parent handles Parent handles Parent handles Coordinator handles
Cost Very low (cache hits) Standard Standard + worktree overhead Higher (coordinator + workers)

Shared infrastructure

All patterns use common infrastructure: - AsyncLocalStorage — isolates concurrent agents in the same Node.js process - Task system — tracks agent state (running/completed/failed/killed) - XML task notifications — standardized completion reporting - ToolUseContext — provides isolated state access with explicit sharing flags

Token-saving optimizations

Across all patterns: - omitClaudeMd — read-only agents (Explore, Plan) drop CLAUDE.md rules, saving ~5-15 GTok/week fleet-wide - gitStatus drop — read-only agents skip gitStatus, saving ~1-3 GTok/week - Fork cache sharing — child requests are byte-identical to parent prefix

Cross-references