Most Claude Code tutorials show you one agent doing one thing. That’s useful. But some problems are too big, too parallel, or too complex for a single agent to handle well.
That’s where multi-agent orchestration comes in. Instead of one Claude doing everything sequentially, you have an orchestrator that breaks a problem into pieces and hands each piece to a subagent — a separate Claude instance with its own context, tools, and instructions. The subagents work in parallel, return their results, and the orchestrator synthesizes everything into a final output.
This guide walks through the pattern from scratch, with working examples you can adapt to your own projects.
Why Multiple Agents?
Three reasons to reach for multi-agent orchestration:
1. Context limits. A single Claude instance can only hold so much in its context window. A codebase audit across 200 files, a research task pulling from 30 sources, a test suite that touches every layer of your stack — these hit limits fast. Subagents each get their own context, so you can process far more than any single agent could handle.
2. Parallelism. Sequential is slow. If you need to review five modules, you could do them one by one — or you could spin up five subagents and get all five reviews simultaneously. Wall-clock time drops from 5× to ~1×.
3. Specialization. Different subagents can have different instructions. A “security reviewer” subagent looks for vulnerabilities. A “performance reviewer” looks for bottlenecks. A “style checker” looks for consistency. Each is primed for its specific task and doesn’t get confused by the others.
The Basic Pattern
Every multi-agent system has the same structure:
Orchestrator
├── Breaks the task into subtasks
├── Spawns Subagent A (subtask 1)
├── Spawns Subagent B (subtask 2)
├── Spawns Subagent C (subtask 3)
├── Waits for all results
└── Synthesizes → final outputIn Claude Code, the orchestrator is a Claude instance that uses the Agent tool to spawn subagents. Each Agent call creates a fresh Claude instance with its own prompt, tools, and context.
Example 1: Parallel Codebase Audit
Let’s say you want to audit a codebase for three things: security issues, performance problems, and code style violations. Sequentially, this takes three full passes. With orchestration, all three happen at once.
The Orchestrator Prompt
You are an orchestrator running a codebase audit.
Your job:
1. Identify the main source directories in this project
2. Spawn three parallel subagents:
- Security reviewer: look for SQL injection, hardcoded secrets, missing auth checks, unsafe deserialization
- Performance reviewer: look for N+1 queries, missing indexes, synchronous calls that should be async, unnecessary loops
- Style reviewer: look for inconsistent naming, functions over 40 lines, missing docstrings on public methods
3. Give each subagent the list of source files to review
4. Collect all three reports
5. Write a combined report to audit-report.md, organized by severity (critical → important → low)
Do not fix anything. Only report findings with file paths and line numbers.What This Looks Like in Practice
When you run this, Claude Code:
- Lists the source files
- Calls the Agent tool three times simultaneously, each with a different system prompt and the same file list
- Each subagent reads through the code with its specific lens
- Results come back, the orchestrator compiles them
A 200-file audit that would take 20+ minutes sequentially runs in 6-8 minutes. More importantly, the security reviewer isn’t distracted by style issues, and vice versa.
Running It
claude "Run a parallel codebase audit on this project. Spawn three subagents — one for security, one for performance, one for code style — and have each review the files in src/. Combine their findings into audit-report.md, prioritized by severity."Example 2: Multi-Source Research Synthesis
You want to research a topic across multiple sources — documentation pages, GitHub issues, blog posts — and synthesize a coherent summary. One agent would read them sequentially and hit context limits. Multiple agents each handle a source and report back.
Setup
Create a file called research-sources.txt:
https://docs.anthropic.com/en/docs/claude-code/overview
https://docs.anthropic.com/en/docs/claude-code/hooks
https://github.com/anthropics/claude-code/issues?q=multi-agent
https://www.anthropic.com/research/building-effective-agentsThe Orchestrator Prompt
You are a research orchestrator. Your task is to synthesize information about
Claude Code's multi-agent capabilities from multiple sources.
Steps:
1. Read research-sources.txt to get the list of URLs
2. Spawn one subagent per URL. Each subagent should:
- Fetch the page content
- Extract key information relevant to multi-agent orchestration
- Return a structured summary: key facts, limitations, examples mentioned
3. Collect all summaries
4. Write a synthesized research brief to research-brief.md that:
- Combines non-duplicate information
- Notes where sources agree or contradict
- Lists the 5 most important takeaways
- Cites which source each claim comes fromWhy This Works Better Than One Agent
Each subagent only sees one source — its context is clean and focused. The orchestrator never reads any of the raw source content; it only sees the structured summaries. This means the orchestrator’s context stays small even if the total raw content across all sources is enormous.
Example 3: Parallel Test Generation
You have a module with 10 functions. You want unit tests for all of them. One agent doing this sequentially takes a while and the later tests are often worse quality as context fills up. Ten subagents, one per function, each produce focused tests with full context available.
The Orchestrator
claude "Look at the functions in src/utils.py. For each function, spawn a subagent that:
1. Reads the function implementation
2. Identifies the key behaviors to test (happy path, edge cases, error cases)
3. Writes pytest tests to tests/test_utils_FUNCTION_NAME.py
Run all subagents in parallel. After they finish, run pytest to verify the tests pass.
Report any failures."Handling Failures
One advantage of the orchestrator pattern: if one subagent fails (say, the function is too complex to test cleanly), it doesn’t take down the whole run. The orchestrator gets a failure report from that one subagent and can handle it — retry, skip, or flag for human review — while the others succeed.
Example 4: The Verifier Pattern
This is the most powerful pattern for high-stakes work. You have an orchestrator that generates something — a piece of code, a report, a plan — and then spawns adversarial verifier subagents whose job is to find flaws in the output.
Setup
Step 1: Generator subagent writes the code
Step 2: Three verifier subagents review it independently
- Verifier A: does it actually solve the stated problem?
- Verifier B: does it handle edge cases?
- Verifier C: are there security implications?
Step 3: Orchestrator reads all three verdicts
Step 4: If 2+ verifiers flag an issue, orchestrator sends back to generator for revision
Step 5: Loop until verifiers pass, or max 3 iterationsWhy Independent Verifiers Work
A single reviewer tends to miss things the generator missed — they share the same blind spots. Three independent reviewers, each primed with a different question, catch far more issues. This is the same reason code review is done by someone other than the author.
Example Prompt
claude "I need you to implement a rate limiter for our API — max 100 requests per minute per user, using Redis.
After you write the implementation:
1. Spawn a correctness verifier: does this actually enforce the limit? Test with edge cases (burst traffic, exactly 100, exactly 101, concurrent requests).
2. Spawn a security verifier: can this be bypassed? Look for race conditions, off-by-one errors, and cases where the limit isn't enforced.
3. Spawn a performance verifier: how does this behave under load? Are there unnecessary Redis round-trips? What's the overhead per request?
If any verifier finds a real problem, revise and re-verify. Stop when all three pass or after 3 revision cycles."Designing Good Subagent Prompts
The quality of your multi-agent system depends almost entirely on how well you write subagent prompts. A few rules:
Give each subagent exactly one job. “Review this code for security and performance and style” produces mediocre results on all three. “Review this code for SQL injection vulnerabilities only” produces excellent results on that one thing.
Tell subagents what format to return. The orchestrator needs to parse results from multiple subagents and combine them. If subagents return inconsistent formats, the orchestrator’s job gets much harder.
Return your findings as a JSON array with this structure:
[
{
"severity": "critical" | "important" | "low",
"file": "path/to/file.py",
"line": 42,
"issue": "Brief description",
"suggestion": "What to do about it"
}
]
If you find no issues, return an empty array: []Be explicit about what subagents should NOT do. Subagents will sometimes try to fix problems they find. That’s often not what you want in an audit or research context.
Do not make any changes to files.
Do not suggest alternative implementations.
Only report what you find, exactly where you find it.Give subagents enough context. Subagents start fresh — they don’t share context with the orchestrator or each other. If a subagent needs to know the project’s conventions to do its review correctly, include those conventions in its prompt or point it to CLAUDE.md.
Managing Costs
Multiple agents mean multiple API calls. For a complex orchestration run, you might spawn 10-20 subagents. A few ways to keep this reasonable:
Cap the scope. Instead of “audit the entire codebase,” try “audit the five files changed in the last PR.” Targeted orchestration is faster and cheaper than broad sweeps.
Use subagents only where parallelism helps. Not every task benefits. If the second subtask depends on the output of the first, you can’t parallelize — just run them sequentially with one agent.
Summarize before synthesizing. Have each subagent return a tight summary rather than full prose. The orchestrator synthesizes summaries, not full reports, keeping its context lean.
Limit retries. In verifier patterns, cap the retry loop (2-3 cycles is usually enough). An infinite retry loop that keeps failing is expensive and almost never converges.
A Full Working Example: PR Review System
Here’s a complete multi-agent system you can use today. It reviews a pull request from multiple angles and produces a prioritized list of comments.
Step 1: Create the orchestrator prompt file
Save this as review-pr.md:
# PR Review Orchestrator
You are orchestrating a multi-angle pull request review.
## Inputs
- Run `git diff main...HEAD` to get the diff
- Run `git log main...HEAD --oneline` to get the commit list
## Subagents to spawn (run in parallel)
### 1. Logic reviewer
Prompt: "Review this diff for correctness. Does the code actually do what the commit messages claim? Are there logical errors, off-by-one issues, or cases that aren't handled? Return findings as a list with file, line, severity (critical/important/minor), and description."
### 2. Security reviewer
Prompt: "Review this diff for security issues. Look for: injection vulnerabilities, authentication bypasses, sensitive data in logs or error messages, insecure dependencies added, and missing input validation. Return findings as a list with file, line, severity, and description."
### 3. Test coverage reviewer
Prompt: "Review this diff. For every new function or modified function, check whether there's a corresponding test change. List any functions that added or changed behavior without test coverage. Return as a list with file, line, and what needs testing."
### 4. Documentation reviewer
Prompt: "Review this diff. Check whether: public functions have docstrings, README is updated if the interface changed, any new environment variables are documented, and complex logic has inline comments. Return as a list of gaps."
## Synthesis
After all four subagents return:
1. Combine all findings
2. De-duplicate (same issue found by multiple reviewers = one entry, highest severity wins)
3. Sort by severity: critical → important → minor
4. Write to pr-review.md in this format:
---
## PR Review — [date]
### Critical (must fix before merge)
[list]
### Important (should fix)
[list]
### Minor (nice to have)
[list]
### Looks good
[things that were done well]
---Step 2: Run it
claude "Read review-pr.md and follow the instructions to orchestrate a full PR review."That’s it. Claude reads the orchestration instructions, spawns four parallel reviewers, and combines the output into a structured report you can use directly in your PR comments.
When Not to Use Multi-Agent
Multi-agent orchestration is powerful, but it’s not always the right tool.
Don’t use it when tasks are sequential. If step 2 requires the output of step 1, you can’t parallelize. Just use one agent doing two steps.
Don’t use it for simple tasks. Spawning three subagents to write a single function is overkill. The orchestration overhead isn’t worth it.
Don’t use it when you need consistent style. Multiple agents writing different parts of the same file will produce inconsistent code. Better to have one agent write everything, then a separate agent review it.
Don’t use it when context sharing matters. Subagents are isolated. If they need to reason about each other’s work while doing their own, they can’t — not in real time. Design the workflow so subagents work on independent pieces, and the orchestrator handles the integration.
Key Takeaways
- Orchestrator + subagents is the pattern: one coordinator, many parallel workers
- Subagents start fresh — no shared context, no awareness of each other
- One job per subagent produces better results than multi-tasking
- Structured return formats make synthesis reliable
- The verifier pattern catches mistakes that a single reviewer misses
- Cost scales with subagent count — scope your orchestration accordingly
The payoff is real: tasks that would take 30+ minutes sequentially run in 5-10. Problems that would overflow a single context window become tractable. And the verifier pattern produces higher-quality output than any single agent can achieve alone.
Once you’ve used it for a real project, going back to single-agent for everything feels like going back to single-threaded code.