You ask Claude to run the whole todo-api test suite and read the log for errors. It gets done, but hundreds of log lines now sit in your conversation, taking up room on every later turn though you will never read them again. This lesson is about handing work like that to a subagent, which does it somewhere else and brings back only the conclusion. More importantly, it is about knowing when to split work off, and when splitting only makes things slower and more expensive.
What a subagent is
Every Claude Code session has a context (the context window: everything Claude is "holding in mind" during the session, including messages, files it has read and command output). That context is limited, and the fuller it gets, the easier it is for Claude to lose track.
A subagent is a helper that runs in its own context, with its own instructions, tools and permissions. Claude hands it a task; it searches, reads and runs commands by itself; when it is done it sends back one summary. Everything it read along the way stays on its side and never spills into your conversation.
Two things to know from the start:
- Subagents aren't free. Each one sends its own requests, and they count toward the same usage limits as your session.
- You don't need a special command. Claude decides on its own to delegate, based on your request and the descriptions of the subagents available. You can also say it outright: "use a subagent to…".
When to split work off, and when not to
The docs give a simple test. Use a subagent when:
- the task produces a lot of output you don't need to keep: running the full test suite, reading logs, searching the whole codebase;
- you want to limit its tools or permissions, for example read-only;
- the work is self-contained and can be summed up when it is done.
Stay in the main conversation when:
- the task needs a lot of back-and-forth to refine;
- the steps share a lot of context, such as planning, writing and testing one feature;
- it is just a quick, small change;
- you need the answer now: a subagent starts from scratch and has to spend time catching up.
Two other options are often confused with subagents:
- For a quick question about something already in the conversation ("which status code did we pick earlier?"), use
/btw. It uses no tools and the answer doesn't go into the history. - For a reusable procedure that runs right in the main conversation, write a skill (level 3).
An easy way to think about it: a subagent is like asking a colleague to look something up and report back. Worth it when the digging is long and you only need the answer. Not worth it when explaining the task takes longer than doing it yourself.
Three built-in subagents
Claude Code ships with a few subagents, and Claude uses them when they fit:
- Explore: read-only (it can't edit files), built for finding and analysing code. When delegating, Claude picks how thorough it should be: quick, medium or very thorough.
- Plan: also read-only, used in plan mode to study the code before presenting a plan.
- general-purpose: has every tool available to subagents, for multi-step work that both investigates and changes code.
There are also a few helper agents such as claude-code-guide, used when you ask about Claude Code itself.
One important detail: Explore and Plan start without your CLAUDE.md and without the git status, to stay fast and cheap. Other subagents load both. Defining subagents of your own is the topic of lesson 4.2.
What a subagent starts with
This is where people trip most often. A subagent (other than a fork, covered in the last section) starts with an empty context. It doesn't see your conversation history, doesn't know which skills you've invoked, and doesn't know which files Claude has read. All it gets is the delegation message Claude writes, plus CLAUDE.md (except for Explore and Plan).
An example: you spend 20 minutes agreeing with Claude that the /admin route is about to be removed and can be ignored. Then you say: "use a subagent to find every route without a test". The subagent reports /admin too, because it never heard that discussion. Claude usually summarises the background when delegating, but nothing guarantees it.
So when you ask for work to be split off, phrase it the way you would brief someone new to the project:
- What to do: "run
npm test". - What to bring back: "report only the failing tests with their error messages".
- Must-follow conditions: "skip the
/adminroute, it is being removed".
"Report only the failing tests" is worth a lot. It keeps the returned summary short, which is the whole reason for splitting the work.
Background and parallel runs
By default, the subagents Claude starts run in the background: you keep typing and asking while they work. Each one shows as a row in the panel below the prompt input. When one finishes, its result arrives in the conversation as a notification. If you ask about progress before then, Claude tells you it is still running.
When a background subagent needs permission, for example to run a command that isn't allowed yet, the prompt appears in your main session, naming the subagent. Approve and it carries on; press Esc and only that one call is refused, while the subagent keeps going and looks for another way.
Because they run in the background, you can hand out several independent tasks at once. Try it on todo-api:
Use two subagents in parallel. One runs npm test and reports only
failing tests with their error messages. The other lists every route
in src/ with the status codes it can return. Then give me a short
combined summary.When we tried it, Claude started two subagents together: general-purpose to run the tests, and Explore, chosen on its own, for listing routes, since that only needs reading. The main conversation received just the two summaries. The combined answer showed that every test passes, yet deleting a todo twice returns 500, a bug the test suite doesn't catch.
A few limits:
- Parallel runs only help when the tasks don't depend on each other. If task B needs task A's result, run them one after the other.
- Every summary still lands in your main context, and every subagent spends tokens of its own. Ten subagents returning ten long reports save nothing.
- By default, at most 20 subagents run at the same time.
Type /tasks to see work in progress and reopen the transcript of a finished subagent when you want to know how it reached its conclusion.
Forks: when the subagent needs the whole story
Sometimes a side task needs most of what you just discussed, and summarising it would take too long. That is when you use a fork: a subagent that carries the entire conversation up to that point. It does its part on its own, and only its final result comes back.
Type /subtask followed by the task:
/subtask draft tests for every 404 case in the route list aboveYou keep working in the main conversation while the fork runs in the background and reports back when done. In the panel, select the fork's row and press Enter to watch what it is doing and send it a message; press x to stop it.
A fork is also cheaper than a fresh subagent for work that needs the same context: it shares the prompt cache with its parent conversation, so its first request doesn't have to be processed from scratch. Don't confuse it with /fork, which copies the whole session into a separate background session and doesn't report back here.
To sum up, ask yourself three questions before splitting work off. Does this task produce a lot of output I don't need? Is it self-contained? Can I explain it in a few lines? Three yeses: give it to a subagent. Needs the whole story: use /subtask. Otherwise, just do it in the main conversation.
Next lesson: defining subagents of your own, with the right tools, model and scope.