What subagents solve
Long sessions hit these inefficiencies:
- Search results and log dumps eat the main context’s token budget
- Self-review by the main agent is biased — it tends to agree with its own work
- Independent tasks run sequentially, wasting wall-clock time
Subagents are helper agents in their own context. Only the result returns to the main conversation, keeping context clean. They also run in parallel.
Define a subagent
A subagent is a markdown file with frontmatter. Where you put it sets its scope and priority:
| Location | Scope | Priority |
|---|---|---|
| Managed settings | Organization-wide | 1 (highest) |
--agents CLI flag | Current session | 2 |
.claude/agents/ | Current project | 3 |
~/.claude/agents/ | All your projects | 4 |
Plugin’s agents/ directory | Where plugin is enabled | 5 (lowest) |
When multiple subagents share the same name, Claude Code uses the one from the higher-priority location. The /agents wizard was removed in Claude Code 2.1.198; ask Claude to create or manage subagents, or edit .claude/agents/ directly.
Example .claude/agents/code-reviewer.md:
---
name: code-reviewer
description: |
Use after a logical chunk of code is written to review it against
the original plan and project coding standards.
tools: Read, Grep, Glob, Bash
model: sonnet
---
You are a senior code reviewer. Given a recent change set, identify:
1. Bugs and logic errors
2. Security vulnerabilities
3. Deviations from project conventions
Report only high-confidence issues. Skip stylistic nitpicks.
Frontmatter fields
Only name and description are required.
| Field | Purpose |
|---|---|
name | Unique identifier used to invoke (required) |
description | When Claude should delegate to this subagent (required; same role as a Skill’s description) |
tools | Tools the subagent can use. Inherits every tool available to subagents if omitted |
model | sonnet, opus, haiku, fable, a full model ID such as claude-opus-5-5, or inherit. When omitted, Claude Code falls back to CLAUDE_CODE_SUBAGENT_MODEL, then the main conversation’s model |
Other supported fields include disallowedTools, permissionMode, maxTurns, skills, mcpServers, hooks, memory, background, effort, isolation, and color. Multi-word fields use camelCase, and Claude Code ignores a field it doesn’t recognize without reporting an error, so watch for typos.
How to invoke
Auto-invocation
When the description matches the situation, the main agent calls the subagent automatically via the Agent tool.
Explicit
Name the subagent in natural language, or @-mention it:
Use the code-reviewer agent to review src/auth/
@"code-reviewer (agent)" look at the auth changes
To run a whole session as a subagent, use claude --agent code-reviewer. To make it the default for a project, set { "agent": "code-reviewer" } in .claude/settings.json. The CLI flag overrides the setting if both are present.
Parallel
In parallel:
- code-reviewer on src/auth/
- security-auditor on dependency vulnerabilities
- test-coverage-analyzer on missing test areas
A subagent that Claude spawns from your main conversation starts in the background by default. Claude keeps working while they run and is notified as each one finishes. By default, 20 subagents can run at once in a session; set CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS to change this.
Forks and nesting
- Forks — a fork inherits the parent conversation instead of starting fresh. Forks are on by default; set
CLAUDE_CODE_FORK_SUBAGENT=0to turn them off. - Nesting — by default, a subagent can spawn subagents of its own, up to three layers below the main conversation. Set
CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1to turn nesting off.
When to use vs skip
| Good fit | Skip |
|---|---|
| Code reviews (independent perspective) | Next step in main work |
| Broad search and exploration | Needs user interaction |
| Security or perf audits | Needs shared progress |
| Concurrent multi-area analysis | Short, simple questions |
| Isolating long output from main context | Output drives main decisions immediately |
Writing a good description
Auto-invocation depends on description quality.
Good
description: |
Use after writing or modifying code in a logical chunk
(a feature, a bugfix, a refactor) to review the change against
the original plan and project coding standards. Reports
high-confidence issues only.
Bad
description: Reviews code # too vague — won't trigger reliably
Restrict tools
The tools field limits what a subagent may use:
tools: Read, Grep, Glob # read-only — cannot modify code
Review and audit agents typically run safest as read-only. To remove specific tools from the inherited set instead, use disallowedTools.
Patterns
Pattern 1: protect main context
For long search results or logs, delegate to a subagent and only get the summary back. The built-in Explore subagent is a fast, read-only agent optimized for searching and analyzing codebases.
Use the Explore agent to find 'authentication' across src/ and report the locations and patterns in 200 chars.
Pattern 2: independent review
Self-review introduces bias. Ask a subagent for an independent take.
Use the code-reviewer agent to independently assess if my recent migration is safe. Don't agree with my analysis — judge on its own.
Pattern 3: parallel analysis
In parallel:
- agent-A on X
- agent-B on Y
- agent-C on Z
Next steps
- Superpowers — includes skills built on subagents, such as subagent-driven-development and dispatching-parallel-agents (the
superpowers:code-revieweragent was removed in v5.1.0) - Code Review, PR Review — review-focused agent collections
- Build a Skill — standardize subagent invocation via Skills
- Subagents docs — full frontmatter reference and current behavior