Fan Out Subagents in Claude Code, Then Check What Comes Back

People type "claude fan out subagents" into Google, and quite a few add "command" at the end, as if there were a switch to flip. There is a pattern, and there is also a command. We checked both on Claude Code 2.1.301 and against Anthropic's documentation on October 16, 2026.

Then there is the part the documentation says little about, and the reason we are writing this: what to do with the results. We run a fan-out every night. Six subagents translate each new post of this blog into seventeen languages, and the main session merges their work. Every one of them reports that it followed the rules. The check we wrote before launching them still finds things.

The short answer

Fan out means one session splits a job into slices that do not depend on each other, hands each slice to a subagent, lets them run at the same time, and merges what comes back. In Claude Code you can do it three ways.

The rest of this page goes through each one, then through the checks we run on our own fan-out.

What a subagent can and cannot see

Three facts from the documentation decide how you slice the work.

Each subagent starts blank. It runs in its own context window, with its own system prompt, tools and permissions. It does not see your conversation, the skills you already used or the files Claude already read. Whatever it needs to know has to be in its brief.

Results come back to the main conversation. The verbose part of a subagent's work stays in its own context and only its result returns. But many subagents returning long reports can still fill your main context, and each one spends tokens of its own while it runs.

There are limits. By default, 20 subagents can run at the same time in a session. The 21st fails with Concurrent subagent limit reached, and the error tells Claude not to retry. You can raise or lower it with CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. Subagents can start subagents of their own, up to three layers below the main conversation, and there is no limit on the total over a session.

Way 1: ask for it in plain words

The simplest fan-out is a sentence. The example in Anthropic's documentation:

Research the authentication, database, and API modules in parallel using separate subagents

Each subagent explores its area, then Claude writes one synthesis. The documentation adds the condition that matters: this works best when the research paths do not depend on each other. If the database question needs the answer to the auth question, you do not have three slices, you have one sequence.

Plain words leave the decision to Claude. If you have defined a custom subagent in .claude/agents/, an @-mention of it guarantees that it runs for that task. Our page on Claude Code subagents covers how those files work.

Way 2: /batch, the closest thing to a fan-out command

/batch is a skill bundled with Claude Code. You give it an instruction:

/batch migrate src/ from JavaScript to TypeScript

It researches the codebase, splits the work into 5 to 30 independent units and shows you a plan. Once you approve, it starts one background subagent per unit, each in an isolated git worktree. Each subagent implements its unit, runs the tests and publishes its change. It needs a git repository, or a WorktreeCreate hook that creates the worktrees for another version control system.

The plan is the moment to slow down. That is where the slicing is decided, and slicing is the whole game: two units that touch the same file, or a unit that needs another one's output, will not merge cleanly however good each subagent is. Read the list of units the way you would read a migration plan from a colleague.

Way 3: a loop over claude -p

When the job is a list of files and you want control over every call, Anthropic's best practices describe a loop. First, have Claude write the list (list all 2,000 Python files that need migrating and save the list to files.txt). Then:

for file in $(cat files.txt); do
  claude -p "Migrate $file from Python 2 to Python 3. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit *)" \
    --permission-mode dontAsk
done

Three details in that example are worth copying.

• The answer is machine-readable. "Return OK or FAIL" means your script can count failures without reading prose.
• Permissions are decided up front. --allowedTools approves exactly what the migration needs, and --permission-mode dontAsk denies everything else instead of waiting for someone who is not there.
• You start with two or three files. The documentation says it plainly: refine the prompt on what goes wrong with the first files, then run the full list.

As written, the loop runs one file after another. Running several calls at the same time is ordinary shell work, but every call is a full session on your machine and on your quota. We measured what happens when several agents start the same heavy command at the same minute in this post, and it is the same story here: start with a small number of parallel calls.

For CI, the documentation recommends adding --bare, which skips hooks, skills, MCP servers and CLAUDE.md so every machine gets the same run. Bare mode does not use your subscription login: it needs ANTHROPIC_API_KEY.

How we fan out every night

Here is the fan-out we actually run. Our nightly SEO team writes each new post in English and French by hand. A second agent then translates it into seventeen more languages with Claude Code subagents, and generates Traditional Chinese from Simplified Chinese with a script instead of translating it. Eleven posts have gone through this since September 13, 2026, each one landing as twenty files.

The slices

Six subagents, three languages each (two for the last one): Spanish, Portuguese and Italian; German, Dutch and Polish; Russian, Ukrainian and Turkish; Japanese, Korean and Chinese; Thai, Vietnamese and Indonesian; Arabic and Hindi. A language never depends on another one, which is what makes this a clean fan-out.

Each brief carries the same five things, because the subagent sees nothing else:

• the English source, and the French version as the reference for tone and product terms;
• for each language, strings already published on the site in that language, so the subagent reuses the words the site already uses instead of inventing new ones;
• the hard rules: brand and product names stay as they are, code stays byte for byte, no em dash;
• the check script, with the instruction to run it until it says OK;
• a request to report anything doubtful it saw, inside or outside its slice.

The check is written before the launch

The check is a script, not a subagent's opinion. For every language it compares the file to the English source:

• same slug and date, title equal to the H1;
• same number of sections, subsections, images, links and table rows, and as many FAQ answers in the body as questions in the metadata;
• links identical byte for byte, code segments identical byte for byte;
• brand names counted, never fewer than in English;
• a length within bounds calibrated for each language, because Chinese says the same thing in about 36 % of the characters English needs and Japanese in about half;
• accents present where the language has them (Polish, Turkish, Vietnamese).

Every subagent finishes with some version of "done, all checks pass". The only verdict we act on is the same script, run again by the main session, on all the files at once.

What the central check caught that the self-reports did not

Code translated inside a table. On September 13, about half of the subagents translated the words that followed a command inside the same backticks of a table. Each one had followed its brief as it understood it. The fix went into the brief, not the subagents: a code segment holds the command only, and the words after it sit outside the backticks.

Our own check was wrong. On September 6, a length check calibrated on the old string we were replacing flagged 11 subagents out of 17. All 11 were right: the new text was supposed to be longer. Calibrated on the corrected French instead, it flagged none. A central check can fail too, and the way to see it is to run it first on a delivery you already know is good.

Consistency across slices. On October 15, on a new feature page translated the same way, the merge check confirmed that only the expected strings had changed across 90 files. But the Japanese, Korean and Chinese subagents had each chosen a different title for "You may also like" than the one their language already used on a neighbouring page. Each choice was a correct translation. None was consistent with the site. No subagent could see that from inside its slice: only a pass over the merged result does.

A wrong word passes every structural check. One language of the site once called AI agents car dealerships, and it stayed online for months. Same length, same punctuation, brand present: every count was green. The only thing that catches it is a named list of known wrong words, which blocks every deployment and grows by one line each time we find a new one.

The reports outside the slice. On October 15, the subagent working on Turkish reported that the site wrote "ajans", agency, for "agent" in 97 existing strings. It did not touch them, because its brief said not to. We opened a ticket and the fix went out the next day. Asking subagents what they saw, not only what they did, is cheap and pays.

The merge happens in one place

Subagents do not write into the repository directly. Each one returns its files, and a script merges them, then compares the result with the previous version string by string: only the strings we asked for may have changed. After that, the repository's checks and the site build run once, on the merged result. Running the build once per subagent would be slower and would test half-merged states that will never ship.

When not to fan out

• The slices depend on each other. If slice B needs slice A's output, run them in order.
• The job is small. Every subagent starts blank and re-reads what it needs. On a ten-minute task, the fresh starts cost more than they save.
• You cannot write the check. If there is no way to tell a good slice from a bad one without reading it all yourself, the merge is where you will spend your time.
• The quota is tight. Each subagent spends its own tokens. Fanning out buys time and a clean main context, not a smaller bill.

Where AgentsRoom fits

Subagents live inside one Claude Code session. You see their results, not their work, and you cannot steer one of them in the middle. When you want each slice to be an agent you can watch, answer and review on its own, run separate sessions instead: each ticket in its own git worktree, and Agent Teams when the slices hand work to each other. A team step can carry a check command, and its exit code, not the agent's own claim, decides whether the run moves on. That is the same rule as above, enforced by the runner. It works with Claude Code, Codex and the other agent CLIs AgentsRoom supports.

If you are still deciding between subagents and agent teams, this comparison explains what each one is for.