Sub-Agents
As you work with Claude Code on real projects, you will encounter a recurring tension: you need Claude to explore something large or tangential, but you do not want that exploration to consume your main context window. Sub-agents solve this problem.
The Task tool spawns an isolated sub-agent — a completely separate Claude instance with its own fresh context window. It receives only the task description you provide, does its work using the same tools available to the main session, and returns a summary of its findings. The critical insight is that only that summary enters your main context. All the intermediate work — the files read, the searches performed, the reasoning — stays in the sub-agent's context and is discarded when it finishes.
Three agents do 90k tokens of work in parallel. Your session receives ~600 tokens of summaries. The agent contexts are discarded.
When Claude (or you) decides to use a sub-agent, here is what happens:
- A new Claude instance is created with a fresh context window.
- It receives only the task description — no conversation history, no previously read files, no accumulated context from the parent session.
- It has access to the same tools as the main session (Read, Write, Edit, Bash, Glob, Grep, WebFetch) — except it cannot spawn its own sub-agents.
- It works through the task autonomously, using the same Gather-Act-Verify loop.
- When finished, it returns a text summary to the parent session.
- Only that summary text is added to the parent's context window.
This isolation is the key feature. A sub-agent might read 30 files and run 15 grep searches to answer a question — that could be 50,000+ tokens of work. But only a few hundred tokens of summary come back to your main session.
Claude Code ships with five built-in sub-agent types, each optimized for a particular kind of work. Run /agents to see them in your own session — the Library tab lists all of them.
| Type | Tools Available | Best For |
|---|---|---|
| Explore | Read-only (Glob, Grep, Read, WebFetch) | Fast codebase exploration. Supports a thoroughness setting — quick, medium, or very thorough |
| Plan | Read-only | Architecture and implementation planning — returns step-by-step plans, identifies critical files, weighs trade-offs |
| general-purpose | All tools | Open-ended research and multi-step tasks when you are not sure where to look |
| claude-code-guide | Glob, Grep, Read, WebFetch, WebSearch | Answers questions about Claude Code, the Agent SDK, and the Claude API |
| statusline-setup | Read, Edit | Configures your Claude Code status line |
Explore and Plan are the workhorses for keeping your main context clean. When you need to understand a large directory structure, trace a complex call chain, or design an approach before writing code, delegating to one of these agents means the investigation does not consume any of your precious main-session tokens.
Sub-agents cannot spawn their own sub-agents. This depth=1 limitation is intentional and important:
- Recursive explosion — without a depth limit, a poorly-scoped task could spawn agents that spawn agents indefinitely, consuming unbounded resources.
- Cost predictability — each sub-agent consumes tokens. Nested agents make costs unpredictable and potentially very large.
- Debuggability — when something goes wrong in a single-level sub-agent, you can reason about what happened. Multi-level agent chains become opaque quickly.
- Reliability — each level of nesting introduces another point of failure. Keeping it flat keeps it reliable.
Think of sub-agents as disposable researchers — you send them on a focused mission, they come back with a report, and your main workspace stays clean.