Parallel subagents: fanning work out across fresh contexts

# Parallel subagents: fanning work out across fresh contexts

A single Claude Code conversation can only think about so much at once, so when the job is genuinely wide, you stop feeding everything into one context and instead fan the work out to subagents: separate Claude instances that each get their own fresh context windowcontext windowThe context window is the maximum amount of text (measured in tokens) a language model can process at once, including both the input prompt and the generated output.View full definition →, work independently, and report back only their conclusions.

You already know the context windowcontext windowThe context window is the maximum amount of text (measured in tokens) a language model can process at once, including both the input prompt and the generated output.View full definition → is finite and that stuffing it degrades quality. Subagents are the structural answer to that problem inside Claude Code. This lesson is about when to reachreachThe number of unique people exposed to your message in a given period. Unlike impressions, reach counts each person once, no matter how often they see it.View full definition → for them, how to define your own, and what you give up in exchange.

What a subagent actually is

A subagent is a child task that Claude Code launches to handle one slice of work. It runs with a clean context, does its job with its own tool access, and returns a summary to the main agent (the orchestrator) that spawned it.

Three properties matter:

• Fresh context. Each subagent starts blank. It does not inherit your main conversation's history. That is the whole point: it is not competing for room with everything else you have been doing.
• Independent execution. Multiple subagents can run at the same time. Claude Code dispatches them and waits for all of them to finish.
• Summary-only return. You do not get the subagent's full transcript back in your main context. You get its conclusion. The messy intermediate reasoning stays isolated.

That last property is the trick that makes fan-out scale. If a subagent reads 40 files to answer one question, those 40 files never touch your main window. Only the answer does.

When parallel fan-out beats one long conversation

Fan-out wins when the work is wide and separable. The pieces do not depend on each other's results, so running them in sequence would just be slower with no benefit.

Good candidates:

• Broad code search. "Find every place we call the payments APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition → and check whether we handle the timeout case." One agent grepping and reading serially will burn through its context. Split it by directory or by service.
• Multi-file audits. Security review, dependency review, accessibility pass. Each concern is a separate lens over the same tree.
• Several genuinely independent tasks. Update the docs, write the migration, and draft the changelog. No shared state, so no reason to serialize.

Fan-out is the wrong tool when the work is deep and sequential: refactoring where step three depends on the result of step two, or debugging a single failure where each finding narrows the next question. There, one continuous conversation keeps the thread. Subagents that cannot see each other would just re-derive the same context and possibly conflict.

The mental model: breadth goes to subagents, depth stays in the main thread.

The briefing tax

Because each subagent starts with nothing, you pay a cost: you must brief it completely. It does not know your architecture, your naming conventions, or what "done" looks like unless you tell it in the dispatch.

A vague dispatch ("review the auth module") produces a vague summary. A subagent has no way to ask you a clarifying question mid-task the way an interactive session does. So the prompt you hand it has to be self-contained:

• What to look at (scope)
• What to look for (the specific question)
• What format to report back in

This is the discipline fan-out forces on you. It is the same discipline good delegation requires from a human: the clearer the brief, the more useful the result.

Custom subagent types

You can define reusable subagent types so you are not re-writing briefs every time. In Claude Code, subagents live as markdown files with YAML frontmatter, either in .claude/agents/ for a specific project or in your user config for all projects.

The frontmatter sets the agent's identity and permissions. The body is its system prompt: the standing instructions it gets every time it runs.

---
name: security-auditor
description: Reviews a directory for injection, auth, and secret-handling flaws. Use for security-focused code review.
tools: Read, Grep, Glob
---

You are a security reviewer. Given a directory path, inspect the code for:
- unsanitized inputs reaching queries, shell calls, or file paths
- missing authentication or authorization checks on sensitive routes
- secrets, tokens, or keys committed in source

Report only confirmed or strongly suspected issues. For each, give the
file, the line range, the risk, and a one-line fix. If you find nothing,
say so plainly. Do not summarize the whole codebase.

Two things worth noticing. The description is what the orchestrator reads to decide when to delegate to this agent, so write it for the router, not for yourself. And tools is deliberately narrow: this agent can read and search but not write or run commands. Least privilege applies to subagents just like it applies to any other automation.

The full schemaschemaA schema is the formal blueprint that defines how data is structured, named, typed, and related within a database, file, or message.View full definition → and the difference between project-level and user-level agents are documented in the Claude Code subagents guide.

A concrete example: auditing a codebase in parallel

Say you inherited a service with four major areas: api/, billing/, auth/, and workers/. You want a fast security read across all of them before a release. Sequentially, one agent would read the whole tree and run low on room somewhere around workers/.

Instead, you tell the orchestrator to fan out. In an interactive Claude Code session that is as simple as asking for it in plain language:

Use the security-auditor subagent to review each of these
directories in parallel: api/, billing/, auth/, and workers/.
Give me one consolidated table of findings sorted by severity.

Claude Code launches four instances of security-auditor, one per directory. Each gets a fresh context, reads only its assigned slice, and returns a short findings list. The orchestrator waits for all four, then merges them into the table you asked for.

What you get back in your main context is compact: four summaries and one merged table. What you do *not* get is the hundreds of lines each agent read to produce those summaries. That is exactly right. You wanted the verdict, not the deliberation.

Contrast this with one long session doing the same review. By the time it reached workers/, the details of api/ would be buried far up the context, competing for attention and quietly degrading the model's precision. Fan-out sidesteps that entirely because no single agent ever holds more than its slice.

Programmatic dispatch with the agent SDK

The interactive flow is great for one-off work. When you want fan-out inside a script or a CI pipelinepipelineAll active sales opportunities across the stages of the sales process, together with their combined potential value and probability of closing.View full definition →, the Claude Agent SDK gives you the same subagent machinery in code, so you can wire a multi-file audit into a pre-release check that runs on every pull request through the GitHub integration.

The pattern is identical: define the agent types once, then let the orchestrator route slices of work to them. The SDK handles the parallel execution and the summary collection so you are not managing threads yourself.

The tradeoffs, stated plainly

Fan-out is powerful, not free. Keep four costs in view.

You lose the transcript. The summary is all you get. If a subagent reaches a wrong conclusion, you cannot easily inspect *how* it got there without re-running it. Design your agent prompts to report evidence (file, line, reason), not just verdicts, so the summary is auditable on its own.

No shared discovery. If the auth/ agent finds a pattern that would help the api/ agent, too bad: they cannot talk. When cross-cutting knowledge matters, either do a first pass to establish shared context and put that in each brief, or keep the work in one thread.

More agents means more tokens. Four fresh contexts each reading files is more total work than one context reading everything once, even though it finishes faster in wall-clock time. You are trading tokentokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.View full definition → efficiency for speed and quality. Usually worth it for wide jobs; wasteful for tiny ones.

Orchestration overhead. Splitting, dispatching, and merging has its own cost in the main context. If a task is small enough that one agent handles it comfortably, fanning out just adds ceremony. Reserve it for jobs that genuinely overflow a single context.

A quick decision rule

Before you fan out, ask: can I split this into pieces that do not need to see each other's results? If yes, and there are more than two or three of them, fan out. If the pieces are entangled, or there are only a couple, stay in one conversation.

How this fits the wider ecosystem

Subagents are a Claude Code construct, but the same shape shows up across Anthropic's tooling. The Agent SDK exposes it for production agents. The Messages APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition → gives you the raw primitive to build your own orchestration if you need something custom. And because subagents inherit MCP connections, each one can reachreachThe number of unique people exposed to your message in a given period. Unlike impressions, reach counts each person once, no matter how often they see it.View full definition → the same tools and data sources (through the Model Context Protocol) that your main session uses, without you rewiring anything per agent.

The through-line: Claude's tooling keeps giving you ways to *isolate* context deliberately rather than letting it accumulate by default. Projects isolate knowledge by workspace. Skills isolate reusable procedures. Subagents isolate a unit of work. Each is a different answer to the same finite-context reality.

Key Takeaways

• Fan out when work is wide and separable, not deep and sequential. Broad searches, multi-file audits, and independent tasks are the sweet spot. Refactors and single-bug hunts belong in one thread.
• Brief every subagent completely. A fresh context means no shared history and no chance to ask you questions. Scope, question, and report format go in the dispatch.
• Define reusable agent types in `.claude/agents/`. Write the description for the router and grant only the tools each agent needs.
• Design prompts to return evidence, not just verdicts. You only get the summary back, so make the summary auditable on its own.
• Know the trade: speed and context-quality up, token cost and cross-agent visibility down. Reserve fan-out for jobs that genuinely overflow a single context.