Subagents let you parallelize Claude. Spawn 8 critics to review your PR. Run 4 codebase searches simultaneously. One turn, many agents, one wall-clock wait.
Learning Objectives
After this lesson, you will be able to:
Define a sub-agent in `.claude/agents/` with the right tools, prompt, and model — for reusable specialized tasks
Distinguish forking (copies your context, one-off) from sub-agent spawn (fresh context, reusable definition)
Use sub-agents to preserve your main context — delegate research, code review, or large file reads to a sub-agent
Recognize when sub-agents win (specialization, isolation) vs when a fork is better (continuation of current task)
You can also hire several specialists at once. Spawn 4 sub-agents to search the codebase four different ways. Spawn 8 critics to review a PR from 8 angles. Spawn a research investigator while a code-reviewer runs and a docs-writer prepares the changelog, all in the same turn.
A sub-agent is a separate Claude Code session with:
Its own context window (starts fresh, doesn't see your main conversation)
Its own permissions (can be more restrictive than parent)
Its own tool set (only the tools you grant)
Its own model (Haiku 4.5 for cheap fanout, Sonnet 4.6 for default work, Opus 4.7 for hard reasoning)
You spawn a sub-agent from your main session via the Agent tool. It runs to completion and returns a single message back. Multiple Agent calls in one turn run in parallel.
# .claude/agents/code-reviewer.yaml
name: code-reviewer
description: Reviews PRs for quality, security, performance, missing tests
tools: [Read, Grep, Glob, Bash]
model: claude-opus-4-7
prompt: |
You are a senior code reviewer. Read the provided diff or files
and produce a focused review. Look for:
- Bugs and edge cases
- Security issues (SQL injection, XSS, secret leaks)
- Performance regressions (N+1 queries, large allocations)
- Missing tests for new logic
- Style/convention violations per the project's CLAUDE.md
Format: bullet list of findings, ordered by severity.
Skip nitpicks unless asked.
Key fields:
name (required) — identifier
description — when to use this agent (used by main session for selection)
tools — allowlist of tools this agent can use
model — Opus for hard work, Haiku for cheap fanout
Multiple Agent calls in a single turn run concurrently:
> Review this PR from three angles in parallel:
> 1. security-reviewer for auth/PII/injection
> 2. performance-reviewer for N+1 and big-O regressions
> 3. test-reviewer for missing coverage
> Then synthesize the three reports into one ranked finding list.
The main session issues three Agent() calls in one turn. They run in parallel, each in its own context. Wall-clock time = max(agent_1, agent_2, agent_3), not the sum. For an 8-file PR, that's 90 seconds total instead of 4.5 minutes sequential.
name: test-generator
description: Generates test cases for a given module
tools: [Read, Edit, Write, Bash]
model: claude-opus-4-7
prompt: |
Read the target module. Generate Vitest/pytest tests covering:
- Happy path
- Edge cases (null, empty, max size)
- Error paths
Run the tests; fix any that fail.
name: research-investigator
description: Multi-source web research with synthesis
tools: [WebFetch, WebSearch, Read]
model: claude-opus-4-7
prompt: |
Research the user's question via multiple sources.
Cross-reference at least 3 reputable sources.
Synthesize a focused answer with source links.
Sub-agents have separate prompt caches, so the first invocation pays for the system prompt + project context. Subsequent invocations within the same session benefit from cache.
For high-frequency sub-agent calls, choose a smaller model (Haiku) and tighter prompts. For one-off complex work, Opus is worth it.
Tests · Verify .claude/agents/code-reviewer.yaml is loaded (run /agents in Claude Code; should see code-reviewer listed). Verify invoking the agent returns a focused review without contaminating your main session.
You're refactoring 8 files in a feature. Halfway through, you want a SECOND opinion on the changes so far. Sub-agent or fork?
Quick check
You're 12 turns into a refactor and want a second opinion on the design so far. Sub-agent or fork?
Sub-agents are how Claude Code implements the multi-agent orchestration patternAgent LoopThe agent loop is the observe-think-act cycle where an AI agent perceives its environment, reasons about the next step, and executes an action.Learn more → from the agents track — each one runs its own reason-act-observe loopReAct PatternThe ReAct pattern interleaves reasoning traces and actions, letting agents think step-by-step before each tool call.Learn more → in isolation, and the main session aggregates their findings.
Sub-agents preserve focus. Next: MCP — how Claude Code talks to external systems like GitHub, Slack, and your databases.