What is a subagent in Claude Code

What is a subagent in Claude Code? A subagent is a worker Claude hands a task to, which runs in its own fresh, isolated context window and reports back only a summary. That is the whole idea. Everything else is detail.

The reason it exists is narrower than the name suggests. A subagent is not Claude getting smarter or more autonomous. It is Claude protecting its own working memory. When a side task would dump a pile of search results, logs, or file contents into your main conversation, contents you will read once and never need again, a subagent does that work somewhere else and brings back just the answer. Your main session never sees the mess.

It helps to picture the failure this is built to prevent. A context window has a fixed size. Everything Claude reads in a session shares that one space: your instructions, the files it opened, the command output, the back-and-forth. Picture a task where Claude greps a large codebase for one function name and gets four hundred matching lines back. Most of those lines are irrelevant to the answer, but they are now sitting in the window, and they stay there. Read enough noise like that and the useful parts of the conversation get crowded out, recall gets fuzzy, and the session starts to drift. The subagent is the fix. The grep still happens, the four hundred lines still get produced, but they get produced in a different room and only the one useful line walks back through the door.

So the deeper question, the one worth the rest of this post, is not what a subagent is. It is when the isolation is worth what it costs. Because a subagent is not free, and reaching for one out of habit is its own kind of mistake. I have written about the broader family of agents, parallel runs, and skills; this post zooms all the way in on the single primitive underneath them.

One way of thinking about it keeps people out of trouble: a subagent is a memory management decision before it is anything else. Not a way to get more done, not a way to be cleverer, not a way to look impressive in a transcript. It is a choice about what your main conversation should and should not have to remember. Hold that thought through the rest of this post, because every tradeoff below comes back to it.

A subagent, defined

Quick rewind here, because the official definition is dry and the dryness hides the point. Start with the official description. Anthropic’s Claude Code subagents documentation puts it in one sentence:

“Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions.” — Claude Code documentation

Unpack that and you have the whole concept. Own context window: the subagent starts fresh and empty, with none of your conversation history, none of the files Claude has already read, none of the skills already loaded. Claude writes it a short delegation message describing the task, and the subagent works from that and nothing else. Custom system prompt: you can give it focused instructions, so a code-reviewer subagent thinks like a reviewer and not like a generalist. Specific tool access: you can hand it only the tools it needs, so a research subagent gets read tools and no write tools. Independent permissions: what it is allowed to do is scoped separately from your main session.

That phrase, “starts fresh and empty,” is worth slowing down on, because it is the part people most often misread. A subagent does not know what you are working on. It does not know which file you were just looking at, which bug you are chasing, or what you decided five messages ago. It gets the delegation message, plus standing material like your CLAUDE.md, and nothing from the conversation itself. So if the task you want done depends on a pile of context that lives in your conversation, that context has to be re-stated in the delegation message or the subagent will get it wrong. The fresh window is a feature when the task is self-contained. It becomes a tax when the task is not. The same property that keeps noise out also keeps the background out, and the background is sometimes the thing you needed.

What I love about this design is that the isolation cuts both ways, and the symmetry is the part most explanations skip. The subagent cannot pollute your main context with its noise. Your main context cannot bias the subagent with irrelevant history. It does one job, in a clean room, and slides the result back under the door. What you get back is a summary, not a transcript. The forty files it read to answer your question do not come back with the answer. That is the entire value, and once you see it that way, the question of when to use one gets much simpler.

The custom system prompt and the scoped tool access matter for a reason that is easy to skip past. A generalist asked to review code for security problems will do an acceptable job, but it carries the whole weight of being a generalist. It might wander. It might also start fixing things you only wanted flagged. A subagent with a reviewer’s system prompt and read-only tools cannot wander far, because the prompt points it at one job and the tool list makes the wrong move impossible rather than merely discouraged. There is a difference between telling a worker not to do something and removing its ability to do it. The second is what scoped tools give you, and it is sturdier than any instruction.

The file behind it

After mulling this over for years of running Claude Code, the answer keeps coming back. A subagent can be ad hoc, spun up for a single task and forgotten. But the version worth understanding is the defined one, because that is just a file you can read.

A custom subagent lives in .claude/agents/ as a Markdown file. The top is YAML frontmatter, the body is the system prompt. The frontmatter fields that carry weight are name, description, tools, and model. The description is doing more work than it looks: Claude reads it to decide when to delegate to this subagent at all, so a vague description means a subagent that never gets used. The tools field is where you enforce constraints, listing only what the subagent may touch. The model field lets you point the subagent at a cheaper, faster model when the task does not need your main model, which is a real cost lever.

The description field deserves more attention than it usually gets, because it is the only field that affects whether the subagent ever runs. The name is a label. The tools and model fields shape how the subagent behaves once it is chosen. But the choice itself, the moment Claude decides this task belongs to this subagent rather than being done inline, hangs on the description. Write “helps with code” and Claude has nothing to match against, so the subagent sits unused while the work happens in the main context anyway. Write something specific about what the subagent is for and when to hand it work, and Claude can route to it reliably. A subagent that is never delegated to is not a subagent. It is a file nobody reads. The description is what turns the file into a worker.

Because it is a file, two things follow that matter for teams. First, a subagent is infrastructure as code. It goes in git, it gets reviewed, and every person on the project inherits the same reviewer or researcher or test-writer. The knowledge of how to do a recurring job stops living in one person’s head. Second, a subagent is legible. When a teammate’s subagent behaves oddly, you open the file and read it. There is no hidden runtime configuration, no dashboard, no magic. The five or six frontmatter fields and the prompt body are the entire surface area. If you can read Markdown, you can audit a subagent.

Think about what that does over time. Picture a team where one person has worked out a good way to review pull requests for a particular kind of mistake the codebase keeps producing. As long as that knowledge lives only in how they prompt Claude, it leaves when they go on holiday and it leaves for good when they change jobs. Move it into a subagent file and it stops being a person’s habit and becomes a thing the project owns. New joiners get it on day one without being told it exists. Someone can improve it in a pull request, and the improvement is reviewed like any other change. When it does the wrong thing, the fix is an edit to a file, not a conversation you have to remember to have. Plain Markdown sitting in version control is an unglamorous format, and that is exactly why it holds up. There is nothing to break and nothing to lose.

Defined versus one-off

I’m torn between calling this a naming problem and calling it a real conceptual gap, because both are true at once. Here is a distinction that trips people up, partly because the names changed. The tool Claude uses to spawn a worker for a single task was called the Task tool. As of Claude Code version 2.1.63 it is the Agent tool, and old Task(...) references still work as aliases. That tool produces an ephemeral worker: it appears, does the one job, returns its summary, and is gone.

A defined subagent, the .claude/agents/ file from the last section, is the opposite kind of thing. It is a persistent specialist. It does not vanish; it sits in the project waiting to be delegated to, with the same instructions and the same tool limits every time.

The distinction matters because the two failure modes pull in opposite directions. Define a subagent for something you do once and you have written a file that will sit in the project forever, mildly confusing the next person who reads the folder and wonders what it is for. Skip the file for something you do constantly and you pay a quieter price: you retype the same guidance every time, and because you are retyping it, it drifts. One day you mention the edge case, the next day you forget it, and the worker behaves differently for no reason you can point to. A defined subagent removes that drift. Same prompt, same tools, same behavior, run after run, whether it is you delegating or a teammate. Consistency is the thing the file buys, and consistency is worth very little for a one-off and worth a lot for a routine.

The official guidance for choosing is refreshingly plain: define a custom subagent when you keep spawning the same kind of worker with the same instructions. If you have asked Claude to “review this for security issues” three times this week and typed roughly the same guidance each time, that guidance wants to be a file. If it really is a one-off, a one-off delegation is correct and writing a file would be overhead. The deeper comparison of one-off delegation against defined specialists, with worked examples, is in the Task tool versus subagents piece. The short version: repetition is the signal. Repeat a worker, define it.

A reasonable way to handle the in-between case is to let one-off delegations come first and promote them later. The first time you need a worker for some task, just delegate. The second time, delegate again and notice that you are repeating yourself. By the third time you have a clear picture of what the instructions should say, what tools the worker needs, and where it tends to go wrong, because you have watched it do the job twice. That is a far better moment to write the file than the first time, when you would have been guessing. Do not rush to define. Let the repetition prove itself, and let the two or three real runs tell you what the file should contain. A subagent file written from a guess tends to be wrong in ways you only discover by using it anyway.

After watching hundreds of teams use Claude Code, the pattern that keeps showing up is the opposite mistake. Teams write three subagents in their first afternoon, before they have run a single delegation. By week two, two of those three files are stale, the third has drifted from how anyone actually uses it, and someone is moaning in Slack about how subagents are rubbish. They are not. The files were just premature. (Premature subagents, like premature optimisation, are their own genre of yak shaving.)

What isolation costs

I’m dubious the cost question gets enough airtime. A subagent is often described as if it were free context savings. It is not. The saving is real, but it is bought.

Strike that. Try this instead: a subagent is a context loan. You borrow a clean window for a side task, and you pay it back in tokens, orchestration, and the work of explaining the job to a worker that has seen none of your conversation. Sometimes the loan is cheap. Sometimes it costs more than the work itself, and that is where teams burn time without realising it.

What you pay is a whole fresh context window. The subagent starts empty, so Claude has to compose a delegation message that re-establishes the task from scratch, since the subagent cannot see the conversation that made the task obvious. The subagent then reads its own files and runs its own tools, all of which consume tokens, just tokens in a different window than yours. Running three subagents in parallel does not divide that cost by three. It triples it and saves you wall-clock time instead. Isolation buys a clean main context. It does not buy a smaller bill.

The delegation message is the part of this cost people tend to forget. It is not free and it is not automatic in the helpful sense. Claude has to look at a task that is obvious in context, because the whole conversation led up to it, and rewrite it as a standalone brief for a worker that has seen none of that conversation. For a tidy, self-contained task that brief is short and the cost is small. For a task that only makes sense against a wall of prior decisions, the brief has to carry all of that prior context, and now you are spending real tokens just to describe the job before any work begins. There is a break-even point hiding in here. If the explaining costs more than the work, the subagent has stopped paying for itself, and you would have been better off just doing the task inline where the context already lived.

There is a lighter-weight variant worth knowing for exactly this reason. A fork is a subagent that inherits the entire conversation so far instead of starting fresh. It gives up the input isolation, since it sees everything your main session sees, but its own tool calls still stay out of your conversation. Use a fork when a clean subagent would need so much background re-explained that the delegation message itself becomes expensive. If you are weighing these tradeoffs across a team and the token bill is what sent you looking, my door is open.

It is worth being clear about what the fork keeps and what it gives up, because the trade is specific. A fork still protects you from output noise. The files it reads and the commands it runs stay in its own window and never land in your conversation, so the main reason you wanted a subagent still holds. What the fork drops is input isolation. It sees your whole history, so it can be nudged by things in that history that have nothing to do with its task, and you no longer get the clean-room effect on the way in. That is the deliberate part of the choice. You accept some input bias to skip the cost of re-explaining everything. When the background is large and the task leans on it, that is a good trade. When the task is properly separate from your conversation, a clean subagent is still the better fit, because then the input isolation costs you nothing and the fork would only be inviting noise back in for no gain.

It is a trade, plainly. You spend tokens and a little orchestration overhead, and you buy back a main context window that stays sharp instead of filling with debris. In a long session that trade is usually worth making. In a short one it usually is not.

I said above that a subagent is “Claude protecting its own working memory.” That oversimplifies it. A subagent does not protect working memory in any general sense; it protects the part of your conversation that is going to matter later from being crowded out by the part that is not. The distinction is small in words and large in practice. A clean memory management decision considers what you will need to refer back to. The intern-in-a-clean-room mental model is shorthand for that, not a substitute for it.

When does a subagent earn it?

Now the part worth slowing down on. So when does the isolation pay for itself? Three signals, and you only need one.

The first is volume. The task will read or generate far more material than its answer is worth: a search across hundreds of files, a long log, the full text of a dozen modules, when all you want back is one paragraph. Send that into a subagent and keep the debris out of your session. Anthropic’s best-practices guide names exactly this pattern, recommending you delegate investigation to subagents so the exploration never consumes your main context.

The test for the volume signal is a ratio, not an absolute size. Ask how much the worker has to read or produce compared to how much of that you actually need to keep. A task that reads three files and reports a two-line answer is fine inline; the noise is small and clearing it would not be worth the delegation. A task that has to open thirty files, scan a long log, and trace a call through a dozen modules to come back with one paragraph is the opposite. The answer is tiny and the path to it is enormous. That gap, between the size of the work and the size of the result, is what a subagent is for. When the gap is wide, isolate. When the work and the answer are about the same size, there is nothing to gain, because there is barely any debris to keep out in the first place.

The second is constraint. You want the work done with a hard limit on what the worker can touch. A research subagent with read-only tools cannot accidentally edit anything. The isolation is not about context here; it is about safety, and a defined subagent with a scoped tools list is how you get it.

The constraint signal is the one people undervalue, because it has nothing to do with token budgets. Imagine you want Claude to investigate something across a repository you care about, and you would rather it could not change a single line while it looks. You could ask it nicely to only read. Or you could hand the job to a subagent whose tool list contains read tools and no write tools, in which case editing is not a thing it can do, regardless of what it decides. Those are different guarantees. An instruction is a request that holds until something overrides it. A missing tool is a wall. For anything that touches code you would hate to see quietly altered, the wall is what you want, and a defined subagent with a scoped tool list is the cheapest way to build one. The clean main context is a bonus here; the real product is a worker that physically cannot do the thing you were worried about.

The third is repetition. You keep doing the same kind of delegated work. That is the signal to stop spinning up ad-hoc workers and write the file, so the next person, including future you, inherits it.

Notice that you only need one of the three. They are not a checklist to satisfy in full. A one-off investigation across a huge codebase earns a subagent on volume alone, even though you will never run it again. A read-only worker for a sensitive directory earns one on constraint alone, even if the task is small. A routine you run weekly earns a defined subagent on repetition alone, even if each run is light. Where it gets easy is when two or three signals stack, because then the decision makes itself. But the more useful habit is the reverse: when you reach for a subagent, name the signal. If you cannot point to volume, constraint, or repetition, you are probably reaching out of habit, and the right move is to put the subagent down and ask Claude directly.

If none of those signals is present, do not reach for a subagent. Just ask Claude directly. The cleanest subagent is the one you did not need to spawn, and a subagent is a tool, not a trophy. Knowing what it is, a fresh isolated worker that hands back a summary, is most of what you need. The rest is just noticing when your task is actually shaped like that, and reaching for the file only then.