Claude Code Subagents
Subagents let Claude Code parallelize work across multiple independent Claude instances. Instead of reviewing 10 modules sequentially in one context window, you spawn 10 subagents — each focused on one module — and collect results in parallel. This page explains when and how to use them.
How Subagents Work
Claude Code implements a two-level architecture:
- Orchestrator — your main Claude Code session. Analyzes the task, breaks it into independent subtasks, spawns subagents, collects results.
- Subagents — fresh Claude instances with their own context windows. Each receives a concise brief from the orchestrator, executes its task, and returns results.
Subagents do not share context with the orchestrator or each other — each starts clean. This makes them efficient (no context bloat) but also means they need self-contained instructions.
Triggering Subagent Parallelism
Tell Claude explicitly to use subagents for parallel work:
# Review all modules in parallel
"Use subagents to review each module in src/ in parallel.
One subagent per module. Report: bugs found, complexity issues,
missing tests. Summarize results when all agents complete."
# Add tests to multiple files simultaneously
"Spawn one subagent per file in src/handlers/ to add unit tests.
Each subagent should create a corresponding .test.ts file.
Use Jest. Mock external dependencies. Aim for 80% branch coverage."
# Multi-language translation
"Use parallel subagents to translate the Python functions in
src/utils.py into TypeScript, Go, and Rust simultaneously.
Each subagent handles one target language."Best Use Cases for Subagents
| Use case | How to partition | Typical speed gain |
|---|---|---|
| Code review across modules | One subagent per top-level directory or service | 5-10× |
| Adding tests to existing files | One subagent per source file or test class | 8-15× |
| Multi-format documentation | One subagent per output format (HTML, Markdown, PDF outline) | 3-4× |
| Dependency audit | One subagent per package.json / requirements.txt | 5-8× |
| Localization | One subagent per target locale | 10-20× |
| API route documentation | One subagent per route group | 5-10× |
| Security audit | One subagent per attack surface (auth, SQL, file handling, etc.) | 4-8× |
When NOT to Use Subagents
• Tasks have hard dependencies (output of step 1 is input of step 2)
• A holistic view of the whole codebase is required (architectural decisions)
• Results must be consistent with each other (e.g., shared naming conventions across files)
• The task is simple enough that spawning overhead outweighs the benefit
Prompting Patterns for Orchestration
# Pattern 1: Directory-based partition
"You are an orchestrator. List all .ts files in src/services/.
Spawn one subagent per file to:
1. Identify exported functions without JSDoc
2. Add JSDoc to each undocumented function
3. Return a summary of how many functions were documented
Collect all summaries and give me a total count."
# Pattern 2: Concern-based partition
"Use three subagents simultaneously to audit this codebase:
- Subagent A: SQL injection risks in src/db/
- Subagent B: XSS vulnerabilities in src/templates/
- Subagent C: Authentication bypass risks in src/auth/
Each should output: findings list + severity (critical/high/medium/low)"
# Pattern 3: Batch processing with coordination
"Process the 20 CSV files in data/raw/ in parallel using 4 subagents.
Assign files 1-5 to subagent A, 6-10 to B, 11-15 to C, 16-20 to D.
Each subagent: validate schema, flag anomalies, write clean file to data/clean/.
After all complete, generate data/summary.json with aggregate stats."The SubagentStop Hook
Use the SubagentStop hook in settings.json to trigger actions when any subagent completes — useful for logging, notifications, or aggregation scripts:
// .claude/settings.json
{
"hooks": {
"SubagentStop": [{
"hooks": [{
"type": "command",
"command": "echo \"Subagent completed at $(date)\" >> ~/.claude-subagent.log"
}]
}]
}
}Cost and Token Considerations
Subagent cost model
Each subagent is a separate API call. 5 subagents processing 5 files each with 1K tokens of input = 5× the API cost of one sequential pass. The speed gain is real but so is the cost multiplier. Use claude-haiku-4-5-20251001 for subagents on routine tasks (review, formatting, documentation) and save Sonnet/Opus for the orchestrator's synthesis step. Estimate costs at Claude Cost Calculator.
Subagents vs Tasks (TaskCreate)
| Feature | Tasks (TaskCreate) | Subagents |
|---|---|---|
| Concurrency | Sequential — one at a time | Parallel — simultaneous |
| Context sharing | Shared with main session | Isolated — fresh context per agent |
| Overhead | Zero — in-session list | One API call per subagent |
| Best for | Breaking a single flow into steps | Independent parallel workstreams |
| Visibility | Task list visible in session | Results returned to orchestrator |
Multi-Agent Architecture Example
# Full pipeline: automated PR review + fix cycle
"You are the orchestrator for this PR review pipeline:
Step 1 — Spawn 3 analysis subagents in parallel:
- Security subagent: review src/ for OWASP top-10 issues
- Performance subagent: review src/ for N+1 queries, missing indexes, slow loops
- Style subagent: check for style guide violations (see CLAUDE.md)
Step 2 — Wait for all 3 to complete.
Step 3 — Synthesize results:
- Combine findings, deduplicate, sort by severity
- Generate pr-review.md with: Executive Summary, Critical Issues (fix before merge),
Suggestions (nice-to-have), Style Notes
Step 4 — For each CRITICAL issue, spawn a fix subagent to:
- Apply the fix
- Write a test that would catch a regression
- Add a comment explaining why this was a bug"Frequently Asked Questions
What are Claude Code subagents?
Independent Claude instances spawned by an orchestrating session to work on tasks in parallel. Each has its own context window and tool access. Results are returned to the orchestrator for synthesis.
How do I trigger subagents?
Describe a parallel task and ask Claude to use subagents: "Use subagents to review each module in src/ simultaneously." Claude will recognize the parallelism and spawn agents automatically.
Do subagents share context with the parent?
No. Each subagent starts with a fresh context containing only the instructions the orchestrator passes to it. This is why they're efficient — no context bloat — but why they need self-contained instructions.
What's the difference between subagents and TaskCreate tasks?
Tasks are a sequential in-session checklist. Subagents are parallel independent Claude instances. Use tasks for step-by-step single-agent work; use subagents when independent pieces of work can happen simultaneously.
What tasks work best with subagents?
Tasks partitioned by file, module, service, or concern: reviewing independent modules, adding tests file-by-file, translating to multiple target languages simultaneously, auditing separate attack surfaces. Avoid when tasks have hard dependencies on each other.
How many subagents can I spawn at once?
No hard limit, but 3-8 is optimal for most use cases. Each subagent costs one API call. Use Haiku for subagent work and Sonnet/Opus for the orchestrator's synthesis to manage costs.
→ Headless Mode — automate Claude Code in CI