---
title: "Claude Code: Multi-Agent Patterns Diagrams"
description: "Agent topologies, worktrees, dual-instance planning, horizontal scaling, decision matrix, cross-session messaging"
tags: [multi-agent, patterns, worktrees, orchestration, scaling]
---
# Multi-Agent Patterns
Patterns for coordinating multiple Claude instances for parallel and complex work.
---
### Agent Teams: 3 Orchestration Topologies
Three proven topologies for multi-agent coordination. Choose based on task independence, ordering requirements, and specialization needs.
```mermaid
flowchart TD
subgraph ORCH["Pattern 1: Orchestrator + Workers"]
OL[Lead Orchestrator] --> OW1[Worker 1
Frontend]
OL --> OW2[Worker 2
Backend]
OL --> OW3[Worker 3
Tests]
OW1 & OW2 & OW3 --> OR([Results aggregated])
end
subgraph PIPE["Pattern 2: Pipeline"]
PA[Agent A
Requirements] --> PB[Agent B
Implementation]
PB --> PC[Agent C
Review]
PC --> PD([Final output])
end
subgraph ROUTE["Pattern 3: Specialist Router"]
RR{Router Agent
analyzes task} --> RC[Code Agent]
RR --> RT[Test Agent]
RR --> RD[Docs Agent]
RC & RT & RD --> RO([Specialized result])
end
style OL fill:#E87E2F,color:#fff
style OW1 fill:#6DB3F2,color:#fff
style OW2 fill:#6DB3F2,color:#fff
style OW3 fill:#6DB3F2,color:#fff
style OR fill:#7BC47F,color:#333
style PA fill:#F5E6D3,color:#333
style PB fill:#F5E6D3,color:#333
style PC fill:#F5E6D3,color:#333
style PD fill:#7BC47F,color:#333
style RR fill:#E87E2F,color:#fff
style RC fill:#6DB3F2,color:#fff
style RT fill:#6DB3F2,color:#fff
style RD fill:#6DB3F2,color:#fff
style RO fill:#7BC47F,color:#333
click OL href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/agent-teams.md" "Lead Orchestrator"
click OW1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/agent-teams.md" "Worker: Frontend"
click OW2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/agent-teams.md" "Worker: Backend"
click OW3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/agent-teams.md" "Worker: Tests"
click OR href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/agent-teams.md" "Results aggregated"
click PA href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/agent-teams.md" "Agent A: Requirements"
click PB href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/agent-teams.md" "Agent B: Implementation"
click PC href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/agent-teams.md" "Agent C: Review"
click PD href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/agent-teams.md" "Final output"
click RR href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/agent-teams.md" "Router Agent"
click RC href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/agent-teams.md" "Code Agent"
click RT href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/agent-teams.md" "Test Agent"
click RD href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/agent-teams.md" "Docs Agent"
click RO href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/agent-teams.md" "Specialized result"
```
ASCII version
```
ORCHESTRATOR + WORKERS: PIPELINE: ROUTER:
Lead Agent Agent A (requirements) Router
/ | \ │ / | \
W1 W2 W3 Agent B (implement) Code Test Docs
\ | / │ \ | /
Aggregate Agent C (review) Result
│
Final output
```
> **Source**: [Agent Teams](../workflows/agent-teams.md), line ~59
---
### Git Worktree Multi-Instance Pattern
Git worktrees enable true parallel development: each Claude instance works in an isolated branch with its own working tree. No conflicts, no context mixing.
```mermaid
flowchart LR
MB[(Main Branch
git repository)] --> WA[git worktree add
feature-A]
MB --> WB[git worktree add
feature-B]
MB --> WC[git worktree add
bugfix-C]
WA --> CA[Claude Instance 1
/worktrees/feature-A]
WB --> CB[Claude Instance 2
/worktrees/feature-B]
WC --> CC[Claude Instance 3
/worktrees/bugfix-C]
CA --> CA1([Commits to feature-A])
CB --> CB1([Commits to feature-B])
CC --> CC1([Commits to bugfix-C])
CA1 & CB1 & CC1 --> MERGE([Merge to main
when ready])
style MB fill:#E87E2F,color:#fff
style CA fill:#6DB3F2,color:#fff
style CB fill:#6DB3F2,color:#fff
style CC fill:#6DB3F2,color:#fff
style CA1 fill:#7BC47F,color:#333
style CB1 fill:#7BC47F,color:#333
style CC1 fill:#7BC47F,color:#333
style MERGE fill:#7BC47F,color:#333
style WA fill:#F5E6D3,color:#333
style WB fill:#F5E6D3,color:#333
style WC fill:#F5E6D3,color:#333
click MB href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#912-git-best-practices--workflows" "Main Branch"
click WA href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#912-git-best-practices--workflows" "Worktree: feature-A"
click WB href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#912-git-best-practices--workflows" "Worktree: feature-B"
click WC href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#912-git-best-practices--workflows" "Worktree: bugfix-C"
click CA href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#912-git-best-practices--workflows" "Claude Instance 1"
click CB href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#912-git-best-practices--workflows" "Claude Instance 2"
click CC href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#912-git-best-practices--workflows" "Claude Instance 3"
click CA1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#912-git-best-practices--workflows" "Commits to feature-A"
click CB1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#912-git-best-practices--workflows" "Commits to feature-B"
click CC1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#912-git-best-practices--workflows" "Commits to bugfix-C"
click MERGE href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#912-git-best-practices--workflows" "Merge to main"
```
ASCII version
```
Main repo
├── git worktree add feature-A → Claude 1 → commits to feature-A
├── git worktree add feature-B → Claude 2 → commits to feature-B
└── git worktree add bugfix-C → Claude 3 → commits to bugfix-C
No conflicts: separate working trees, separate branches
All merge back to main when done
```
> **Source**: [Git Worktrees](../ultimate-guide.md#git-worktrees), line ~10634
---
### Dual-Instance Planning Pattern (Jon Williams)
Separating planning from execution using two Claude instances prevents costly mistakes: the planner Claude has no tools, so it can't accidentally execute anything during analysis.
```mermaid
sequenceDiagram
participant U as User
participant PL as Planner Claude
(no tools)
participant EX as Executor Claude
(full tools)
U->>PL: "Plan how to refactor auth module"
Note over PL: Reads docs, analyzes requirements
No execution risk — no tools
PL->>U: Detailed plan:
1. Files to change
2. Order of operations
3. Risk points
4. Rollback strategy
U->>U: Review plan carefully
Note over U: Human checkpoint:
approve or adjust
U->>EX: "Execute this plan: [plan text]"
EX->>EX: Implements step by step
EX->>U: Progress updates + results
Note over PL,EX: Key insight: planner can be
more thorough without execution anxiety
```
ASCII version
```
User → Planner (no tools): "Plan X"
│
[safe analysis, no execution risk]
│
Planner → User: detailed plan
│
User reviews + approves
│
User → Executor (full tools): "Execute: [plan]"
│
[implements with full context]
│
Executor → User: results
```
> **Source**: [Dual-Instance Planning](../workflows/dual-instance-planning.md)
---
### Boris Cherny Horizontal Scaling Pattern
When tasks can be parallelized, spawn N Claude instances simultaneously instead of running them sequentially. The speedup is proportional to task independence.
```mermaid
flowchart LR
BT([Large Task:
Refactor 50 files]) --> DEC{Decompose
into N subtasks}
DEC --> T1["Subtask 1
Files 1-10"]
DEC --> T2["Subtask 2
Files 11-20"]
DEC --> T3["Subtask 3
Files 21-30"]
DEC --> TN["Subtask N
..."]
T1 --> CI1[Claude
Instance 1]
T2 --> CI2[Claude
Instance 2]
T3 --> CI3[Claude
Instance 3]
TN --> CIN[Claude
Instance N]
CI1 & CI2 & CI3 & CIN --> AGG(Aggregate
results)
AGG --> REV([Integration review
~10x faster than sequential])
style BT fill:#F5E6D3,color:#333
style DEC fill:#E87E2F,color:#fff
style CI1 fill:#6DB3F2,color:#fff
style CI2 fill:#6DB3F2,color:#fff
style CI3 fill:#6DB3F2,color:#fff
style CIN fill:#6DB3F2,color:#fff
style AGG fill:#B8B8B8,color:#333
style REV fill:#7BC47F,color:#333
click BT href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#917-scaling-patterns-multi-instance-workflows" "Large Task"
click DEC href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#917-scaling-patterns-multi-instance-workflows" "Decompose into subtasks"
click T1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#917-scaling-patterns-multi-instance-workflows" "Subtask 1"
click T2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#917-scaling-patterns-multi-instance-workflows" "Subtask 2"
click T3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#917-scaling-patterns-multi-instance-workflows" "Subtask 3"
click TN href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#917-scaling-patterns-multi-instance-workflows" "Subtask N"
click CI1 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#917-scaling-patterns-multi-instance-workflows" "Claude Instance 1"
click CI2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#917-scaling-patterns-multi-instance-workflows" "Claude Instance 2"
click CI3 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#917-scaling-patterns-multi-instance-workflows" "Claude Instance 3"
click CIN href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#917-scaling-patterns-multi-instance-workflows" "Claude Instance N"
click AGG href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#917-scaling-patterns-multi-instance-workflows" "Aggregate results"
click REV href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#917-scaling-patterns-multi-instance-workflows" "Integration review"
```
ASCII version
```
Large task
│
Decompose into N independent subtasks
│
┌────┼────┐
│ │ │
I1 I2 I3... (parallel)
│ │ │
└────┼────┘
│
Aggregate → Integration review
(~10x faster than sequential)
```
> **Source**: [Horizontal Scaling](../ultimate-guide.md#horizontal-scaling), line ~9617
---
### Multi-Instance Decision Matrix
Not every task needs multiple instances. This decision tree guides you to the right pattern based on task characteristics.
```mermaid
flowchart TD
A([Task to complete]) --> B{Need multiple
Claude instances?}
B -->|No| C([Single session
Standard usage])
B -->|Yes| D{How many
instances?}
B -->|"Planning separation?"| B2{Need planning
separation?}
D -->|2-3| E{Need branch
isolation?}
E -->|Yes| F([Git worktrees
Separate branches])
E -->|No| G([Multiple terminals
Same repo])
D -->|4+| H{Task structure?}
H -->|Independent tasks| I([Task tool
Sub-agents in parallel])
H -->|Sequential pipeline| J([Agent pipeline
A → B → C])
H -->|Mixed expertise| K([Specialist router
Route by task type])
B2 --> L([Dual-instance
Planner + Executor])
style A fill:#F5E6D3,color:#333
style B fill:#E87E2F,color:#fff
style D fill:#E87E2F,color:#fff
style E fill:#E87E2F,color:#fff
style H fill:#E87E2F,color:#fff
style B2 fill:#E87E2F,color:#fff
style C fill:#B8B8B8,color:#333
style F fill:#7BC47F,color:#333
style G fill:#7BC47F,color:#333
style I fill:#7BC47F,color:#333
style J fill:#7BC47F,color:#333
style K fill:#7BC47F,color:#333
style L fill:#6DB3F2,color:#fff
click A href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#917-scaling-patterns-multi-instance-workflows" "Task to complete"
click B href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#917-scaling-patterns-multi-instance-workflows" "Need multiple instances?"
click C href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#917-scaling-patterns-multi-instance-workflows" "Single session"
click D href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#917-scaling-patterns-multi-instance-workflows" "How many instances?"
click E href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#912-git-best-practices--workflows" "Need branch isolation?"
click F href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#912-git-best-practices--workflows" "Git worktrees"
click G href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#917-scaling-patterns-multi-instance-workflows" "Multiple terminals"
click H href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/ultimate-guide.md#917-scaling-patterns-multi-instance-workflows" "Task structure?"
click I href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/agent-teams.md" "Task tool sub-agents"
click J href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/agent-teams.md" "Agent pipeline"
click K href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/agent-teams.md" "Specialist router"
click B2 href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/dual-instance-planning.md" "Need planning separation?"
click L href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/dual-instance-planning.md" "Dual-instance: Planner + Executor"
```
ASCII version
```
Need multiple instances?
├─ No → Single session
├─ Yes → How many?
│ ├─ 2-3 → Need branch isolation?
│ │ ├─ Yes → Git worktrees
│ │ └─ No → Multiple terminals
│ └─ 4+ → Task structure?
│ ├─ Independent → Task tool (parallel sub-agents)
│ ├─ Sequential → Agent pipeline A→B→C
│ └─ Mixed → Specialist router
└─ Planning separation? → Dual-instance (Planner + Executor)
```
> **Source**: [Multi-Instance Patterns](../ultimate-guide.md#multi-instance-patterns), line ~11176
---
### Cross-Session Messaging: Discovery & Delivery
Independent Claude Code sessions, no spawn relationship between them, discover each other with `ListAgents` and message each other with `SendMessage`. Whether the message ever touches Anthropic's servers depends entirely on where the target session runs.
```mermaid
flowchart TD
subgraph DISCOVER["Discovery: ListAgents"]
SA(Session A
repo-a) -->|registers on start| REG[(On-disk registry
+ inbox socket)]
SB(Session B
repo-b) -->|registers on start| REG
REG --> LA[[ListAgents reads registry]]
LA --> ROWS[[/list-agents rows:
subagents, teammates,
local peers, cloud, Remote Control/]]
end
subgraph DELIVER["Delivery: SendMessage"]
ROWS --> SM{Target session
runs where?}
SM -->|Same machine| SOCK[Unix socket / named pipe
never through Anthropic servers]
SM -->|Other machine or web| RC{{Remote Control channel
through Anthropic servers}}
SOCK --> GATE{crossSessionInbound
on receiving side}
RC --> GATE
GATE -->|accept| DELIVERED([Delivered to
receiving Claude])
GATE -->|hold| HELD([Held: user must
click Approve])
GATE -->|refuse| DROPPED([Dropped,
never delivered])
end
DELIVERED --> BOUND(Receiving session's own permission
rules still apply. Message text alone
cannot approve or reconfigure anything.)
style SA fill:#F5E6D3,color:#333
style SB fill:#F5E6D3,color:#333
style REG fill:#B8B8B8,color:#333
style LA fill:#6DB3F2,color:#fff
style ROWS fill:#6DB3F2,color:#fff
style SM fill:#E87E2F,color:#fff
style SOCK fill:#B8B8B8,color:#333
style RC fill:#B8B8B8,color:#333
style GATE fill:#E87E2F,color:#fff
style DELIVERED fill:#7BC47F,color:#333
style HELD fill:#F5E6D3,color:#333
style DROPPED fill:#E85D5D,color:#fff
style BOUND fill:#7BC47F,color:#333
click SA href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/cross-session-messaging.md#2-discovery-listagents" "Session A"
click SB href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/cross-session-messaging.md#2-discovery-listagents" "Session B"
click REG href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/cross-session-messaging.md#5-the-sessions-inbox-socket" "On-disk registry"
click LA href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/cross-session-messaging.md#2-discovery-listagents" "ListAgents"
click ROWS href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/cross-session-messaging.md#2-discovery-listagents" "list-agents rows"
click SM href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/cross-session-messaging.md#4-same-machine-vs-cross-machine-delivery" "Target session runs where"
click SOCK href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/cross-session-messaging.md#4-same-machine-vs-cross-machine-delivery" "Same-machine socket"
click RC href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/cross-session-messaging.md#4-same-machine-vs-cross-machine-delivery" "Remote Control channel"
click GATE href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/cross-session-messaging.md#6-security-model" "crossSessionInbound"
click DELIVERED href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/cross-session-messaging.md#6-security-model" "Delivered"
click HELD href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/cross-session-messaging.md#6-security-model" "Held"
click DROPPED href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/cross-session-messaging.md#6-security-model" "Dropped"
click BOUND href "https://github.com/FlorianBruniaux/claude-code-ultimate-guide/blob/main/guide/workflows/cross-session-messaging.md#6-security-model" "Permission boundary"
```
ASCII version
```
DISCOVERY DELIVERY
Session A ─┐ list-agents rows
Session B ─┴─> on-disk registry │
+ inbox socket ▼
│ Target runs where?
▼ ├─ Same machine ──> local socket ──┐
ListAgents reads (never via Anthropic servers) │
│ └─ Other machine/web ──> Remote │
▼ Control (via Anthropic) ──────┤
list-agents rows ▼
crossSessionInbound?
├─ accept ─> delivered
├─ hold ───> user must Approve
└─ refuse ─> dropped
Delivered message still cannot approve permissions or change config;
the receiving session's own permission rules apply to anything it asks for.
```
> **Source**: [Cross-Session Messaging](../workflows/cross-session-messaging.md)