Subagents

A subagent is a separate Claude Code instance, with its own context window, dispatched to handle a scoped piece of work and report back a result — rather than everything happening in one long, growing conversation.

Why a separate context window matters

The main conversation's context is a shared, finite resource. A broad investigation — searching across an entire codebase, reading through a dozen files to understand a subsystem, working through a long and noisy debugging trail — can consume a lot of that budget on intermediate steps that don't need to stay visible once the answer is found. Running that work in a subagent keeps the noise contained: the subagent does the exploring, and only its conclusion comes back into the main conversation.

When delegating makes sense

• An independent, parallelizable piece of work — reviewing a diff for issues while other work continues, or investigating two unrelated parts of a bug report at the same time.
• A broad, exploratory task with an uncertain amount of reading involved, where you want the answer without the main conversation absorbing every file that got opened along the way.
• A task that benefits from a fresh, unbiased perspective — a second pass reviewing code that was just written, run by an agent that wasn't the one that wrote it and isn't anchored to the reasoning that produced it.

When it doesn't

For something small, sequential, and already well-scoped — reading one file, making one targeted edit — delegating to a subagent adds overhead without buying anything; the main conversation can just do it directly. Subagents earn their cost on work that's either large enough to pollute context or genuinely benefits from running independently, not as a default for every step.

The trade-off to keep in mind

A subagent starts with none of the main conversation's context and returns only a summary, not its full working transcript. That's the entire point — isolation — but it means a subagent needs to be briefed with enough context to do the job well, the same way you'd brief a colleague picking up a task cold. A vague instruction to a subagent tends to produce a vague result, since it has nothing else to fall back on.

A concrete example

Asked to "make sure this refactor didn't break anything in the payments module," a reasonable approach is dispatching a subagent specifically to review the payments module against the diff, while the main session continues addressing other feedback — rather than the main conversation pausing to read through an entire unrelated module itself.

This closes out core capabilities. The next section covers the configurable features that shape how Claude Code behaves on a given project.