Subagents in Claude Code: Working in Parallel

A subagent is a separate session the main agent launches for a specific task. It has its own context, its own result, and no memory of your conversation.

What a subagent is

The analogy is simple: you hand a task to somebody who was not at the meeting. They will do exactly what the brief says and return a result. Anything you left out, they do not know.

In practice: the main agent frames the task, launches a subagent, that subagent works in its own context window and returns an outcome. Only the outcome enters the main session, not everything read along the way.

That is the main benefit. Searching a large repository returns three pages of output; done in the main session those three pages stay in context forever. A subagent reads them in its own window and returns a paragraph.

When to delegate and when not to

Worth delegating:

• Reconnaissance. “Find where file uploads are handled and describe the flow.” A lot of reading, a short answer.
• Independent analysis. Testing a hypothesis, reviewing an unfamiliar module, finding similar code elsewhere.
• Uniform work over a list. Ten files, the same change in each.
• Verification. A separate subagent looking at the result with fresh eyes catches what the author of the change cannot see. That technique is covered on the blog: the agent verification layer.

Not worth delegating:

• A task you have not framed yourself. The subagent will not ask.
• Work that needs the whole conversation. Restating it is longer than doing it.
• A small edit. The overhead of the brief exceeds the gain.
• Parallel edits to one file. That is a conflict, and untangling it costs more than doing the work in sequence.

Running tasks in parallel

Several subagents on independent tasks is the biggest visible win on wall-clock time. There is exactly one condition: the tasks must genuinely be independent.

A good example: check five modules for the same problem. Each subagent takes one module, nobody blocks anybody, the results are collected at the end.

A bad example: three subagents editing the same file from different angles. The last one overwrites the others, or you end up with half-applied changes.

The working rule: parallelise reads, serialise writes.

Checking the result

A subagent returns text. Text reads as convincing whether or not it is true - a general property of language models that no amount of phrasing fixes. Hence three rules:

1. Demand a verifiable result. Not “check that everything is fine” but “run the tests and include the output”. A verifiable claim can be rechecked; a judgement cannot.
2. Do not accept conclusions without sources. If a subagent says a function is unused, it should show where it looked.
3. Read the diff, not the report. The report describes intent, the diff shows fact. They diverge more often than you would like.

This is the same principle as in any agent system: trust is built on verification, not on a confident tone. The long version is in guardrails for agents in production.

Next

The general theory of delegation between agents is in the AI agents guide. Subagents pair naturally with skills: a documented procedure can be delegated whole. On context spend, see limits. The overview is in the Claude Code guide.