Subagents — the mental model
Subagents are isolated Claudes with their own context, tools and prompt — invoked by the main Claude like a function call. Master them and your throughput jumps.
The metaphor
Think of the main Claude as a tech lead. Subagents are specialist contractors the lead hires for a specific job. The contractor:
- Doesn't know about other tasks the lead is juggling
- Has only the tools needed for their job
- Works independently and reports a single result
- Can work in parallel with other contractors
Why this matters
Two big wins:
1. Parallelism. "Dispatch three subagents to research X, Y, Z" runs them simultaneously. One wall-clock unit does three units of work.
2. Context isolation. A subagent's intermediate exploration (10 grep calls, 5 Read calls) never enters the main conversation. The main Claude sees only the subagent's final summary. Token cost drops dramatically on long tasks.
When not to subagent
- Single-step tasks — dispatch overhead exceeds benefit.
- Tasks that need the full conversation history.
- Tasks tightly coupled to context built up in the main thread.
Where subagents live
Two locations:
~/.claude/agents/<name>.md— personal, available everywhere.<project>/.claude/agents/<name>.md— project-specific, committed for the team.
Each subagent is one markdown file with frontmatter and a system prompt. We'll build one in the next lesson.
Built-in vs custom
Claude Code ships with a handful of useful subagents (general-purpose, code-reviewer in some bundles). Custom subagents are where the real leverage is — they encode your team's workflow.
How dispatch happens
Three ways the main Claude can invoke a subagent:
- Explicit user request — "Use the Explore subagent to find X."
- Inferred from CLAUDE.md — your CLAUDE.md instructs Claude to use Explore for search.
- Tool-driven — the main Claude calls the Agent tool, names the subagent, passes a prompt.
The output contract
A subagent runs to completion and returns one final message. The main Claude treats that message as the result. The subagent's tool calls and intermediate reasoning are not visible to the main thread.
That makes prompt design important: a subagent prompt must produce a self-contained, useful result.
Try it
List the kinds of "side quests" that took your last Claude session off-track (long greps, exploring an unfamiliar module, running tests). Each one is a subagent candidate.