A subagent is a fresh copy of your agent, sent off with its own context window to do messy work and report back only the answer. Used for context control, not role-play, subagents keep your main session sharp: exploring, running noisy tests, reviewing with fresh eyes, or trying several designs at once.
Key takeaways
- A subagent is a fresh copy of the agent with its own context window; only its summary comes back.
- Subagents are for context control, not role-play personas.
- Great uses: exploring a codebase, running verbose tests, fresh-eyes review, trying several designs in parallel.
- Parallel subagents shine on breadth-first work; most coding tasks have fewer independent pieces.
- Don't over-split: handoffs between agents are a common failure point.
Try it with your agent
In Claude Code, Codex or any agent with subagents:
Use a subagent to explore how [feature] works across the codebase and report back under 300 words, with file paths. Then use a second, fresh subagent with no knowledge of my plans to review [file] for bugs. Tell me roughly how much context each used.
Transcript
Intro
What if your agent could clone itself, send the clone off to do the messy work, and get back just the answer? That's a subagent, and it's one of the best tools you have for keeping context clean.
What it is
Simon Willison's definition: when a coding agent uses a subagent, it effectively dispatches a fresh copy of itself to achieve a specified goal, with a new context window that starts with a fresh prompt.
Context isolation
Here's why that matters. The main agent writes a short brief and hands it to the subagent. The subagent burns through tens of thousands of tokens, searching and reading files. Then it returns a compact summary, maybe a thousand or two thousand tokens. As Thorsten Ball puts it, all the garbage tokens stay out of your main context.
In one of Matt Pocock's sessions, an explore subagent used almost ninety-four thousand tokens of its own, and the main context barely moved. Thorsten calls this the multiplication of context windows: every subagent call is a whole new window.
Not role-play
There's a popular misconception. People build teams of personas: a front-end developer agent, a QA agent, a product manager agent. Dex Horthy is blunt about it: subagents are not for anthropomorphizing roles. They are for controlling context. Boris Cherny adds that the real value is uncorrelated context windows that don't know about each other.
Good uses
So what are subagents good for? Exploring: Claude Code often sends an explore subagent before touching an existing repo. Running a verbose test suite and reporting only the failures. Reviewing with fresh eyes, since an agent reviewing its own work tends to go easy on itself. And trying several designs at once: Matt Pocock spawns three subagents, each told to produce a radically different interface.
Fan out, then filter
Subagents also enable a powerful pattern: fan out, then filter. Boris describes a code review command that sends parallel subagents to look for problems from different angles. Then several more subagents check each finding for false positives, so you only see real issues.
When parallel pays off
How much can this help? On Anthropic's internal research benchmark, a lead agent coordinating parallel subagents outperformed a single agent by ninety percent. But they're careful to add that most coding tasks have fewer truly independent pieces than research, and agents aren't yet great at coordinating each other in real time.
Pitfalls
A few pitfalls. Don't over-split: Simon Willison warns against dozens of specialist subagents. Watch the handoff: Will from Anthropic says a subagent can get its task right and still fail because the message back to the orchestrator lost something. And for big outputs, have subagents write to files and pass back a path, instead of a game of telephone.
Quick check
Quick check. Which of these is the best use of a subagent? Tap your answer.
Try it
Try both classic uses in one go. One subagent explores and reports back a short map. A second, with no knowledge of your plans, reviews a file with fresh eyes.
Recap
Recap. A subagent is a fresh copy with its own context window. Use it for context control, not role-play. Explore, run noisy work, review with fresh eyes, try alternatives. Fan out, then filter. And don't over-split. Next: running whole agents in parallel.