# How subagents split work and share context

The single biggest jump in what an agent can do is not a smarter model. It is the moment one agent learns to spawn others. A subagent lets the main agent hand off a self-contained piece of work, get a clean result, and keep going. Do that across several pieces at once and the agent stops working like a single person and starts working like a small team.

This guide is about three things that make that work: **fanning out**, **context**, and **which model each subagent runs**. You drive all of it from the CLI; you do not write the orchestration yourself.

## How do agents fan out?

Fanning out means [splitting independent work across subagents](/guides/run-agents-in-parallel) that run at the same time. The main agent (the **orchestrator**) decides the breakdown, starts the subagents, waits for their results, then stitches them together.

The win is wall-clock time and focus: three subagents reviewing three modules finish in roughly the time of the slowest one, and each only has to think about its own corner.

The catch is that fan-out only helps when the work is **independent**. If subagent B needs subagent A's answer first, running them in parallel buys you nothing. The orchestrator's real job is deciding what can run side by side and what has to wait.

| Fan out when | Keep it sequential when |
| --- | --- |
| The pieces touch different files or systems | One step's output is the next step's input |
| Each piece has a clear, self-contained goal | The task is one tangled thread of reasoning |
| You want breadth fast (review, search, audit) | A subtle change needs one consistent train of thought |

## Why does each subagent start fresh?

This is the part people miss. A subagent does **not** share the orchestrator's full context window. It gets a tight brief, builds its own context by reading what it needs, and returns only a result.

That isolation is a feature, not a limitation:

- **The orchestrator's context stays clean.** A subagent might read twenty files to answer one question. Only its conclusion comes back, not the twenty files. The main thread does not fill up with noise.
- **Each subagent thinks clearly.** It is not distracted by the other branches of work. Its whole window is about its one job.
- **You trade a little duplication for a lot of clarity.** Two subagents might each re-read a shared file. That costs some tokens, but it keeps each one's reasoning focused, which is usually the better deal.

The practical lesson: give each subagent a brief that is complete on its own. It cannot see what you told the orchestrator, so spell out the goal, the constraints, and what a good result looks like. This is [Context Engineering](/guides/context-engineering) applied one level down.It is tempting to write a one-line brief like "review the auth module" and assume the subagent can see the orchestrator's plan and the files already discussed. It cannot: it starts blank, so a thin brief makes it guess the goal and read the wrong files. Name the exact files, the constraint, and what "done" looks like inside the brief itself.

## Which model should a subagent use?

By default a subagent runs on the **same model** as the orchestrator. That is the safe choice and often the right one. But you can set the model per subagent, and that is where cost control lives.

The idea: spend a strong model where the thinking is hard, and a smaller, faster, cheaper model where the work is mechanical.

| Subagent's job | Model to give it |
| --- | --- |
| Hard reasoning, architecture, tricky bugs | Inherit the main (strong) model |
| Search, summarise, gather files, simple lookups | A smaller, faster, cheaper model |
| Bulk, repetitive passes across many items | The cheapest model that gets it right |

In Claude Code you define a subagent as a small markdown file under `.claude/agents/`, and its frontmatter is where you set the model:

```markdown
---
name: file-finder
description: Locates the files relevant to a task and reports their paths.
model: haiku
---

Find the files involved in the task you are given. Report only their paths and a
one-line note on what each does. Do not edit anything.
```

The orchestrator runs on your session's model; this finder runs on a cheaper one. You get the breadth without paying the strong-model rate for grunt work.Do not put a cheap model on a subagent whose job is judgement, like spotting a security bug. It returns a confident, tidy answer that reads fine, and the orchestrator trusts it. Match the model to the hardest decision the subagent makes, not the average one. Run `/agents` to see and manage the subagents available in a project.

## When does fanning out pay off?

Fanning out with mixed models is powerful, but it is not free. More agents means more tokens in flight and more results to reconcile.

- **Worth it:** a broad review or audit, searching a large codebase, generating several independent things, any task that decomposes cleanly.
- **Not worth it:** a small change, or one continuous thread of hard reasoning. A single agent on a [higher effort level](/guides/claude-code-effort-levels) will do better than a committee.

The mental model is the same one you use for a team: hand out work that is separable, give each person a brief they can act on alone, and do not pay a senior rate for a job a junior can do. The orchestrator is the lead; the subagents are the team; the models are the seniority. When one agent's job is to delegate and combine the rest, you are using the [orchestrator-worker pattern](/guides/orchestrator-worker-agents).

Review this pull request by fanning out: one subagent per changed module, each checking correctness and edge cases in its files only. Use a cheaper model for any subagent that only gathers context. Then combine the findings into one prioritised list.