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.

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.

A subagent, defined

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.

The isolation is the point, and it cuts both ways. 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 file behind it

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.

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.

Defined versus one-off

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 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.

What isolation costs

A subagent is often described as if it were free context savings. It is not. The saving is real, but it is bought.

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.

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 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.

When a subagent earns it

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 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 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.

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.