Subagents are the unit of parallelism in Claude Code. One session spawns another, passes a prompt, gets a result back. No shared memory, no lateral communication, no inherited context. This isolation is the point. It keeps the parent context clean and lets you run focused workers in parallel without coordination overhead.
What Subagents Are
A Claude Code subagent is an isolated Claude session spawned by a parent session through the Agent tool. The parent passes a prompt string. A new Claude instance starts with a fresh context window containing that prompt, a minimal system prompt, and basic environment details. The subagent works autonomously, making tool calls, reading files, running commands. When it finishes, its final message returns to the parent as the Agent tool result. All intermediate reasoning and tool outputs stay inside the subagent's context.
That single round trip is the entire interface. One string in, one string out. The subagent has no access to the parent's conversation, and the parent has no visibility into the subagent's intermediate steps.
Built-in Subagents
Claude Code ships three subagent types that it uses automatically based on task requirements:
Explore
Runs on Haiku for speed. Read-only tool access (no Write or Edit). Purpose: codebase search and file discovery. Claude delegates here when it needs to understand code without changing it. Supports quick, medium, and very thorough modes.
Plan
Inherits the parent model. Read-only tool access. Used during plan mode to gather codebase context before presenting a plan. Prevents infinite nesting since subagents cannot spawn other subagents.
General-purpose
Inherits the parent model. Has access to all tools. Handles complex multi-step tasks that require both exploration and modification. Claude delegates here for tasks needing reasoning across multiple dependent steps.
What a Subagent Sees
Context isolation is the defining property of subagents. A subagent's context window starts empty except for four things:
| Included | Excluded | |
|---|---|---|
| System prompt | From the markdown body of the agent file | Parent's full Claude Code system prompt |
| Task context | The prompt string from the Agent tool call | Parent's conversation history |
| Environment | Working directory, platform, shell | Parent's prior tool calls and results |
| Skills | Only those listed in the skills frontmatter field | Skills loaded in the parent session |
| MCP servers | Only those listed in mcpServers frontmatter | Parent's MCP server tool descriptions (unless configured) |
| Other subagents | Nothing from other subagents | Other subagents' outputs (unless parent relays them) |
The prompt string is the only channel
If a subagent needs file paths, error messages, architectural decisions, or output from a previous subagent, the parent must include it in the Agent tool prompt. There is no other way to pass context. Front-load everything the subagent needs to start working immediately.
This isolation is the main reason to use subagents. Running tests, fetching documentation, or processing log files can consume significant context. By delegating to a subagent, the verbose output stays in the subagent's context window. Only the summary returns to the parent. This keeps the parent's context focused on the actual work.
Configuring Custom Subagents
Custom subagents are markdown files with YAML frontmatter. Store them in .claude/agents/ for project scope (check into version control for team sharing) or ~/.claude/agents/ for user scope (available across all projects). You can also pass them as JSON via the --agents CLI flag for session-only agents.
.claude/agents/code-reviewer.md
---
name: code-reviewer
description: Reviews code for quality, security, and best practices. Use proactively after code changes.
tools: Read, Glob, Grep, Bash
model: sonnet
permissionMode: dontAsk
---
You are a senior code reviewer. When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Review for correctness, security, and readability
Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)
Include specific code examples for each fix.Frontmatter Reference
| Field | Required | What It Controls |
|---|---|---|
| name | Yes | Unique identifier (lowercase, hyphens) |
| description | Yes | When Claude delegates to this agent (the routing signal) |
| tools | No | Allowlist of tools. Inherits all if omitted |
| disallowedTools | No | Denylist. Removed from inherited or specified tools |
| model | No | sonnet, opus, haiku, or inherit (default: inherit) |
| permissionMode | No | default, acceptEdits, dontAsk, bypassPermissions, plan |
| maxTurns | No | Maximum agentic turns before the subagent stops |
| skills | No | Skill content injected at startup (not just available for invocation) |
| isolation | No | Set to 'worktree' for git worktree isolation |
| memory | No | Persistent scope: user, project, or local |
| background | No | true to run concurrently without blocking parent |
| hooks | No | PreToolUse, PostToolUse, Stop lifecycle hooks |
The description field is the most important configuration choice. Claude uses it to decide when to delegate. Write descriptions that explain when the subagent should run, not just what it does. "Reviews code for quality and security. Use proactively after code changes." is better than "Code reviewer."
Priority Order
When multiple subagents share a name, the higher-priority location wins: CLI flag (session) > .claude/agents/ (project) > ~/.claude/agents/ (user) > plugin agents (lowest).
Subagents vs Agent Teams
Both parallelize work, but the communication model is fundamentally different. Subagents report to one parent. Agent teams communicate laterally.
| Subagents | Agent Teams | Direct Tool Calls | |
|---|---|---|---|
| Communication | Result returns to parent only | Teammates message each other directly | Inline in conversation |
| Context | Own window, isolated | Own window, independent | Shared with parent |
| Coordination | Parent manages all work | Shared task list, self-coordination | None needed |
| Parallelism | Multiple can run simultaneously | Teammates work in parallel | Sequential |
| File isolation | Optional worktree per agent | Each teammate gets a worktree | None |
| Token overhead | Moderate (per-agent context) | High (per-teammate context + messaging) | Lowest (shared context) |
| Best for | Focused tasks, verbose operations | Complex work requiring discussion | Simple, quick operations |
The decision heuristic
If a worker only needs to return a result, use a subagent. If workers need to talk to each other during execution, use agent teams. If the task is simple enough to not need isolation at all, use a direct tool call. Agent teams are experimental and require the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS flag.
Parallel Subagents and Worktrees
Running multiple subagents simultaneously is the primary performance advantage. Each subagent gets its own context window. For file changes, git worktrees provide filesystem isolation so parallel edits never collide during execution.
.claude/agents/parallel-worker.md
---
name: parallel-worker
description: Handles independent code changes in its own worktree
tools: Read, Edit, Write, Bash, Grep, Glob
isolation: worktree
model: sonnet
---
You are a focused implementation agent. Work in your
isolated worktree. Make changes, run tests to verify,
and report what you changed and whether tests pass.When isolation: worktree is set, each subagent invocation creates a separate git checkout. The subagent works on its own branch with its own working directory and index. Clean worktrees (no changes) are deleted automatically when the subagent finishes. Worktrees with changes persist for review.
Choose Independent Tasks
The biggest factor in avoiding merge conflicts is task selection, not tooling. If two subagents touch the same file, you'll get conflicts at merge time regardless of worktree isolation. Split work so each subagent owns different files.
Merge One at a Time
When parallel subagents finish, merge each branch back to main sequentially. If tasks were truly independent (different files), merges are clean. If conflicts appear, it signals the tasks weren't independent enough.
You can also trigger parallel subagents from natural language: "Research the authentication, database, and API modules in parallel using separate subagents." Claude spawns multiple agents, each exploring its area independently, then synthesizes findings.
The Communication Protocol
The protocol is a single round trip. The parent sends a prompt via the Agent tool. The subagent executes autonomously, making however many tool calls it needs. When it stops, the parent receives the final message as the Agent tool result. No streaming, no progress updates, no mid-execution interrupts.
Unstructured Return
The subagent's final message returns as natural language text. The parent interprets and may summarize it. Good for research tasks, code review findings, and exploratory work where the format varies.
Structured Return (SDK)
In the Claude Agent SDK, pass an outputFormat option with a JSON schema. The subagent's response includes a structured_output field with validated data. Good for programmatic orchestration where the parent needs to parse results.
File-Based Communication
Subagents can write findings to files that the parent or other subagents read later. Useful for chaining: first subagent writes REVIEW.md, second subagent reads REVIEW.md before starting implementation.
Background vs Foreground
Foreground subagents block the parent conversation until they complete. Permission prompts pass through to the user. Background subagents (set background: true or say "run this in the background") run concurrently. Before launching, Claude prompts for all permissions the subagent will need upfront. Once running, unapproved tool calls are auto-denied. Press Ctrl+B to background a running subagent.
Subagent Patterns
Research Subagent
Explore codebase with read-only access, return a summary. Keeps verbose grep/find output out of the parent context. The built-in Explore agent handles this for most cases. Custom agents add domain-specific instructions.
Test Runner Subagent
Run the full test suite and report only failures. Test output can be hundreds of lines. The subagent absorbs it all and returns a focused summary: 3 tests failed, here are the error messages and file locations.
Code Review Subagent
Analyze recent changes for security, performance, and correctness. Restrict to read-only tools (Read, Grep, Glob, Bash) so the reviewer cannot accidentally modify code. Returns prioritized findings.
Database Query Subagent
Execute read-only SQL queries using a PreToolUse hook that validates Bash commands and blocks INSERT/UPDATE/DELETE. Returns analysis results without risk of data mutation.
Documentation Subagent
Fetch and process external documentation that would consume significant context. The subagent reads the docs, extracts relevant sections, and returns a concise summary the parent can act on.
Cost-Optimized Subagent
Route simple tasks to Haiku (model: haiku) for lower token costs and faster execution. The Explore agent already does this by default. Custom Haiku agents work well for classification, formatting, and data extraction.
Chaining subagents from the parent
Use the code-reviewer subagent to analyze src/auth/ for
security issues. Then use the debugger subagent to fix
any critical issues it finds.
# Claude runs code-reviewer first, gets findings back,
# then passes relevant findings to debugger in its prompt.Token Costs and Optimization
Every subagent invocation creates a new context window. The cost depends on the model, the system prompt size, MCP server descriptions, and task complexity.
| Agent Type | Model | Typical Tokens | Use Case |
|---|---|---|---|
| Explore (quick) | Haiku | ~5K | Targeted file lookups |
| Explore (thorough) | Haiku | ~15K | Comprehensive codebase analysis |
| General-purpose | Sonnet | 30-50K | Complex multi-step tasks |
| Custom (with MCP) | Varies | 50K+ | Tasks using multiple MCP servers |
Reducing subagent costs
Route simple tasks to Haiku (model: haiku). Limit MCP servers per subagent to only those it needs (each adds 10-20K tokens of tool descriptions). Set maxTurns to prevent runaway sessions. Enable persistent memory so subagents build up codebase knowledge across sessions instead of re-exploring every time.
Persistent memory is a compounding investment. When a subagent with memory: user or memory: project runs repeatedly, it writes codebase patterns, file locations, and architectural decisions to its memory directory. Future invocations read this memory and skip redundant exploration. Over time, this reduces both token consumption and execution time.
Frequently Asked Questions
What are Claude Code subagents?
Isolated Claude sessions spawned by a parent session through the Agent tool. The parent sends a prompt string. A new Claude instance starts with a fresh context window. When it finishes, the final message returns to the parent. Intermediate tool calls stay inside the subagent. Three built-in types: Explore (Haiku, read-only), Plan (inherits model, read-only), and General-purpose (inherits model, all tools).
What context does a subagent receive?
Only four things: the prompt string from the parent, the system prompt from its markdown file, environment details (working directory, platform), and any skills listed in its skills frontmatter. It does not inherit the parent's conversation history, prior tool calls, or other subagents' outputs.
How do you create a custom subagent?
Create a markdown file with YAML frontmatter in .claude/agents/ (project) or ~/.claude/agents/ (user). Required fields: name and description. Optional: tools, model, permissionMode, maxTurns, skills, isolation, memory, hooks, background. Or use the /agents command for interactive creation. Or pass JSON via --agents for session-only agents.
What is the difference between subagents and agent teams?
Subagents report results to one parent and cannot communicate with each other. Agent teams let teammates message each other directly, share task lists, and self-coordinate. Use subagents for focused tasks where only the result matters. Use teams when workers need to share findings or coordinate on runtime dependencies.
Can subagents run in parallel?
Yes. Multiple subagents run simultaneously in their own context windows. For file isolation, set isolation: worktree to give each subagent its own git checkout. Choose independent tasks that touch different files to avoid merge conflicts. Worktrees without changes are cleaned up automatically.
How much do subagents cost?
Each subagent has its own context window. Explore on Haiku costs approximately 5K tokens per invocation. General-purpose on Sonnet costs 30-50K tokens. MCP tool descriptions add 10-20K tokens per session. Running 5 parallel subagents costs roughly 5x a single session. Use model: haiku, limit MCP servers, and enable persistent memory to reduce costs over time.
Parallel Subagents Generate More Code. Apply It Faster.
Running 5 subagents in parallel produces 5x the code changes. Each edit needs to merge cleanly into your codebase. Morph's Fast Apply model handles LLM-generated diffs at 10,500+ tokens per second with deterministic merging. The reliability layer your subagent pipeline needs.