Understanding Sub-Agents
As tasks grow larger, doing everything in a single conversation becomes a problem — context fills up, details get compressed, and quality drops. Sub-agents are Claude Code's answer: a main agent manages the work while specialist agents handle each piece in their own separate context window.
What is a sub-agent?
A sub-agent is a separate Claude instance that Claude Code spawns to handle a specific task. It has its own context window, works independently, and returns only a short summary back to the main agent. The main agent stays lean — it never sees the sub-agent's full working context.
- Own context window
- Works independently on a focused task
- Returns summaries only — not full file reads and diffs
- Spawned automatically when a task is complex enough
The architecture
Let the main agent manage — let sub-agents do the work. Each sub-agent is a specialist. The main agent only receives a short summary when the sub-agent finishes.
Main Agent
Plans work, delegates tasks, reads summaries
Explorer
Read-only search
Finds files, reads code, maps the codebase
Coder
Write & edit
Creates files, makes changes, runs commands
Reviewer
Quality check
Reviews code, flags issues, never edits
Only short summaries return to Main — not the full working context
Why sub-agents matter — the context problem
Every Claude conversation has a context window. When it fills up, Claude compresses (compacts) older content. Important details get lost, earlier decisions are forgotten, and quality drops — even if you have not noticed it happening.
| Single conversation | Delegated to sub-agents | |
|---|---|---|
| Context growth | Grows with every file read and edit | Main stays small; heavy work happens elsewhere |
| Compaction risk | At ~80% Claude compresses older details | Main typically stays under 20% |
| Quality over time | Degrades silently over long sessions | Stays high — main only sees summaries |
| Best for | Short, focused tasks | Multi-step builds across many files |
| Context | Typical usage | Effect |
|---|---|---|
| Main — without sub-agents | ~80% | Compaction kicks in; older details may be lost |
| Main — with sub-agents | ~15% | Only summaries added; no compaction risk |
| Sub-agent context | ~70% | Works freely in its own window; main unaffected |
Common sub-agent types
Claude Code ships with built-in sub-agents for the most common tasks. You can also define custom sub-agents for your project's specific needs.
| Agent | Role | Example task |
|---|---|---|
| Explorer | Read-only codebase navigator — searches and reads, never writes | Find all API routes that use the Stripe client |
| Coder | File writer and editor — creates files, runs commands | Implement the POST /api/checkout endpoint |
| Reviewer | Quality checker — returns structured feedback, never edits | Review the new auth middleware for security issues |
| Tester | Test writer and runner — handles all testing work | Write and run tests for the new formatCurrency utility |
A simple worked example
Task: “Add email notifications when a new user signs up.” The main agent orchestrates sub-agents to complete it as follows.
| Step | Agent | Action | Summary |
|---|---|---|---|
| 1 | Main Agent | Receives the task. Plans: explore auth code, code the mailer, test it, review. | Task plan created |
| 2 | Explorer Agent | Reads src/app/api/auth/, finds signup at register/route.ts line 34. | Signup happens in register/route.ts at line 34 |
| 3 | Coder Agent | Creates src/lib/mailer.ts, edits register/route.ts, installs nodemailer. | mailer.ts created, route updated, nodemailer added |
| 4 | Tester Agent | Writes src/__tests__/mailer.test.ts. Runs npm run test. All 3 pass. | 3 tests written, all passing |
| 5 | Reviewer Agent | Reviews mailer.ts and route changes. Flags missing email validation. | 1 suggestion: validate email before sending |
| 6 | Main Agent | Reads all four summaries. Asks Coder to add the validation. | Done — email validation added. Task complete. |
How Claude invokes sub-agents
In most cases Claude Code handles sub-agent dispatch automatically when a task is complex enough. You can also invoke them explicitly in your prompt.
Automatic — Claude decides
For larger tasks Claude Code automatically plans and delegates to the right sub-agents. You just describe the outcome.
Explicit — you name the agent
Call a specific sub-agent type by name to make intent clear — especially useful for review-only or explore-only tasks.
Before you continue
- Sub-agents work in separate context windows and return short summaries to main.
- Main agent plans and delegates; sub-agents do focused work.
- Delegation keeps main context lean and avoids compaction on long tasks.
- Tell reviewer and explorer agents not to edit — report only.
- Next lesson: Create a Sub-Agent.
What's Next
Sub-agents covered. The next lesson walks through building one from scratch — role definition, instructions, and allowed tools.