There is a ceiling to how much a single AI session can hold in its head. Point Claude Code at a big enough task — search this whole codebase, review these forty files, investigate why the build is flaky — and you watch its context fill with logs, file dumps, and dead ends until the thing it was actually trying to do gets crowded out. Subagents are the escape hatch. They let one Claude spin up others, each working in its own clean context, and report back only what matters.
What a subagent is
A subagent is a separate Claude with its own isolated context window, its own (optionally restricted) tools, and its own system prompt. The main session delegates a task to it; the subagent does the work; and — this is the key part — only the subagent's final summary comes back. All the noise it generated along the way stays in its context, not yours.
That single property is why subagents are worth understanding. They buy you:
- Context preservation. A search that reads fifty files returns a three-line answer to the main session, not fifty files' worth of text.
- Constraint. You can hand a "reviewer" agent read-only tools so it physically cannot edit anything.
- Specialization. A focused system prompt makes an agent good at one job.
- Cost control. Route a mechanical task to a cheaper, faster model like Haiku while the main session stays on a stronger one.
The built-in agents you already have
Before you write your own, know the ones that ship with Claude Code:
- Explore — read-only, optimized for fast codebase search and analysis. It cannot edit, and it skips loading your CLAUDE.md and git status for speed. This is the workhorse for "where is X handled?"
- Plan — read-only research used in plan mode to investigate before proposing an approach.
- General-purpose — full tool access for complex, multi-step work that needs both exploration and action.
For a huge fraction of tasks, "use the Explore agent to find every place we validate emails" is all the delegation you need.
Defining your own
A custom subagent is just a markdown file with YAML frontmatter, dropped in one of two places:
.claude/agents/*.md— project-scoped, shared with your team via git~/.claude/agents/*.md— user-scoped, available in all your projects
The shape:
---
name: code-reviewer
description: Reviews code for quality and best practices. Use right after writing code.
tools: Read, Grep, Glob, Bash
model: sonnet
---
You are a senior code reviewer. When invoked, analyze the changes and give
specific, actionable feedback organized by severity. Do not rewrite the code —
point to the exact lines and explain the risk.
Only two frontmatter fields are required: name (lowercase, hyphenated) and description (which tells the main agent when to delegate here). Everything else is optional — the ones you will reach for most are tools (an allowlist; omit it to inherit everything), model (haiku, sonnet, opus, or inherit), and a disallowedTools blocklist. The body of the file is the agent's system prompt.
The description is doing real work: it is how the main Claude decides whether a task belongs to this agent. "Reviews code" is weak; "Use right after writing code to catch bugs and style issues" tells Claude exactly when to reach for it.
How you invoke them
Three ways, in increasing order of certainty:
- Just ask. "Use the code-reviewer agent to look at my auth changes." Claude decides whether to delegate.
- @-mention. Typing
@agent-code-reviewerguarantees that agent runs — no guessing. - Whole session.
claude --agent code-reviewer(or setting it in.claude/settings.json) runs the entire session as that agent.
Running many at once
This is where subagents earn their keep. Recent Claude Code runs subagents in the background by default — the main session spawns them and keeps working while they run, with results arriving as they finish. So "review each of these five modules" can become five agents working in parallel instead of one agent grinding through them serially. When independent work can be fanned out, fanning it out is often several times faster in wall-clock terms.
The gotchas
Subagents are powerful precisely because they are isolated, and that isolation is also the source of every mistake people make with them:
- They do not share your context. A subagent starts fresh. It has not seen your conversation, the files you already read, or your earlier tool calls — only the delegation message you (or Claude) hand it. If it needs context, you have to pass it explicitly.
- You only get the final message back. Everything the subagent explored is gone once it returns its summary. If you needed the details, ask it to include them in the summary.
- They nest, but not infinitely. Agents can spawn agents up to about five levels deep. Design flows that fan out wide, not stack deep.
- Explore and Plan skip your CLAUDE.md. For speed, those two don't load your project rules — fine for search, worth remembering if a rule seems ignored.
When not to reach for one
Subagents add latency and cost a round-trip of context-passing, so they are the wrong tool for tight back-and-forth, quick one-off edits, or any task that shares a lot of state with what you are already doing. The sweet spot is the opposite: a chunky, self-contained job that produces a lot of intermediate noise and a small useful result. Search, review, investigation, and large parallelizable sweeps are exactly that — which is why "delegate the messy part, keep the summary" is the mental model that makes subagents click.