Running Claude Code Subagents in Parallel

Claude Code subagents are specialized, isolated instances of Claude that a main session can delegate work to, and running several of them in parallel is how you cut a 20-minute sequential task down to the length of its slowest single piece. Instead of asking one agent to search the codebase, then review a diff, then run tests, one after another, you hand out those three jobs at once and let them execute concurrently. This guide covers how subagents are defined, how to dispatch them in parallel correctly, and the mistakes that quietly turn "parallel" into "accidentally sequential."

What Claude Code Subagents Actually Are

A subagent is a separate agent loop with its own context window, its own tool permissions, and (optionally) its own system prompt. It is not a thread inside your current conversation. When the main Claude Code session delegates a task to a subagent, that subagent reads only what you tell it in the prompt, does its work, and returns a single result. It cannot see your scrollback, and you cannot see its intermediate tool calls unless you ask it to report them.

You define a subagent as a markdown file with YAML frontmatter, typically under .claude/agents/ in your project (or ~/.claude/agents/ for agents you want available across every project):

---
name: test-runner
description: Runs the test suite and reports failures with file:line references.
tools: Bash, Read, Grep
model: sonnet
---

You are a test-running specialist. Run the project's test command,
parse failures, and report each one as a path:line plus a one-line
cause. Do not attempt to fix anything, only diagnose.

Three fields matter most for parallel work:

• tools: restrict this to the minimum the agent needs. A research agent that only reads files should not have Write or Bash access.
• model: pin a cheaper or faster model for high-volume, low-complexity fan-out work, and reserve the strongest model for the piece that needs real judgment.
• description: this is what the orchestrating agent uses to decide when to invoke this subagent automatically, so write it as a trigger condition, not a summary.

Once the file exists, the main session can invoke it by name. That single invocation is cheap. The leverage comes from invoking several of them in the same turn.

Why Parallel Dispatch Matters for Claude Code Subagents

The default behavior, if you ask for three things in three separate messages, is sequential: agent one finishes, then agent two starts, then agent three starts. Each subagent has its own context window, so nothing is shared between them and there is no correctness reason to wait. The only reason execution ends up sequential is that you asked for it one request at a time.

Parallel dispatch fixes this by issuing multiple subagent calls inside a single assistant turn. The orchestrator fires off all of them together, and total wall-clock time collapses to roughly the duration of the slowest branch instead of the sum of all branches. For a workflow like "find every place a deprecated function is called, review the diff for security issues, and run the affected test suite," that is the difference between one long wait and three short ones happening at once.

There is a second, less obvious benefit: context isolation. If you ran all three of those jobs in one long-lived agent, its context window would fill with file contents, diffs, and test output that have nothing to do with each other, and the agent's judgment on any one task degrades as irrelevant context piles up. Splitting the work into subagents keeps each one focused, and only the final summaries flow back into the parent's context, not the raw exploration.

Setting Up Subagents for Parallel Execution

Start by writing focused agent definitions. A parallel fan-out only pays off if each subagent has a narrow, well-scoped job. Here are three agents that commonly run together on a pull request review:

---
name: security-reviewer
description: Reviews a diff for injection, auth, and secrets issues. Use after any change touching input handling or credentials.
tools: Read, Grep, Bash
model: opus
---

Review the current diff for security issues only: injection,
broken auth checks, hardcoded secrets, unsafe deserialization.
Report each finding as path:line, severity, and a one-line fix.
Do not comment on style or naming.

---
name: test-runner
description: Runs the test suite for changed files and reports failures.
tools: Bash, Read
model: sonnet
---

Run the test command for this project. If it fails, isolate which
test file and line caused it. Report pass/fail counts and a short
list of failures, nothing else.

---
name: doc-checker
description: Checks whether README and inline docs still match the changed code.
tools: Read, Grep
model: haiku
---

Compare the current diff against README.md and any docstrings for
the changed functions. Flag anything now inaccurate. Keep the
report to a bulleted list.

Notice the model choice varies by task complexity. Security review benefits from the strongest reasoning available; checking whether docs are stale does not. Mixing model tiers across your parallel fan-out is a real cost lever, not a micro-optimization, once you are running dozens of these a day.

Dispatching Multiple Subagents in One Turn

The mechanism that makes parallel execution happen is simple: put more than one subagent invocation in the same response. If you are driving Claude Code interactively, you can just ask for it directly:

Review this PR: run the security-reviewer, test-runner, and
doc-checker subagents on it in parallel, then summarize all
three results together.

The main agent recognizes that these three tasks are independent, no shared state, no ordering dependency, and issues all three subagent calls together instead of one at a time. If you notice the agent running them sequentially anyway, be explicit about the independence:

These three checks don't depend on each other. Dispatch all
three subagents in parallel in a single turn, not one after
another.

This is worth saying out loud because a model asked to "review, then test, then check docs" will sometimes read "then" as a sequencing instruction rather than a list separator. Framing the request as a batch of independent jobs, rather than a numbered sequence, removes the ambiguity.

For scripted or SDK-driven usage, the same principle holds: the calling code should issue all subagent requests together and wait on the combined result, rather than looping over tasks and awaiting each one before starting the next.

# Sequential: total time = sum of all three
review = run_subagent("security-reviewer", diff)
tests = run_subagent("test-runner", diff)
docs = run_subagent("doc-checker", diff)

# Parallel: total time = slowest of the three
import asyncio

results = asyncio.gather(
    run_subagent_async("security-reviewer", diff),
    run_subagent_async("test-runner", diff),
    run_subagent_async("doc-checker", diff),
)

Whether you are typing prompts or writing orchestration code, the rule is the same: independent tasks go out together, dependent tasks go out in order.

Foreground vs Background Subagents

Not every subagent needs to block your session. A subagent can run in the foreground, where the parent waits for its result before continuing, or in the background, where the parent keeps working and gets notified when the subagent finishes.

Use foreground dispatch when the subagent's output changes what you do next. If a research subagent is investigating whether a bug exists in three different modules, and you need that answer before deciding what to fix, wait for it.

Use background dispatch when the subagent's job is long-running and doesn't block your immediate next step. A common pattern:

Kick off the full test suite as a background subagent while I
keep reviewing the diff for style issues. Let me know when it's
done.

This lets you use your own attention productively instead of sitting idle while a ten-minute test run finishes. The key discipline is not to poll. Asking "is it done yet?" every thirty seconds burns turns for no benefit; the orchestration layer notifies you when a background subagent completes, so keep working until that notification arrives.

A frequent mistake here is launching several background subagents that all write to the same file or depend on each other's output. Background parallelism only works cleanly when the tasks are truly independent, same as foreground fan-out. If subagent B needs subagent A's result, run A in the foreground, then dispatch B once A returns.

Common Parallel Subagent Patterns

Fan-out research. When a question spans a large codebase, split it by area rather than running one agent that reads everything. "Find every usage of the old auth token format" becomes three subagents, one per top-level directory, each returning a short list of file:line matches. The parent merges the lists. This is faster and keeps any single subagent's context window from ballooning with irrelevant files.

Independent review lenses. Security, performance, and style are separable concerns. Running one agent that tries to catch all three at once produces a shallower review than three focused agents each looking for one class of problem. Dispatch them together, merge the findings, dedupe overlapping line references.

Multi-file content generation. If you need five similar files written (five component tests, five documentation pages, five config variants), a subagent per file, dispatched together, avoids one agent doing them serially and losing consistency on the fourth or fifth file as its context fills up.

Verification after a change. After an edit, run a test subagent and a lint subagent together rather than sequentially. Both read the same changed files but do not depend on each other's output, so there is no reason to wait.

A pattern to avoid: spawning ten subagents for ten trivial one-line tasks. The overhead of setting up an isolated agent, giving it a prompt, and parsing its return is not free. Parallel dispatch pays off when each branch does meaningful, independent work, not when you are parallelizing something that would have taken five seconds as one plain tool call.

Debugging and Monitoring Parallel Subagents

When something goes wrong in a batch of parallel subagents, the first question is which one failed and why, and the isolated-context design that makes subagents fast also makes debugging them slightly less visible than watching a single agent work step by step.

A few practices help:

• Ask each subagent to report its own confidence and any assumptions it made, not just its final answer. A test-runner subagent that silently assumed the wrong test command will produce a clean-looking but wrong report.
• If a subagent's task is genuinely uncertain (a broad codebase search, for example), have it state what it did not check, not just what it found.
• When results conflict, for example a security-reviewer subagent flags a line that a doc-checker subagent describes as intentional, resolve that in the parent turn rather than asking one subagent to adjudicate the other's work. The parent has the full picture; the subagents each only have their slice.
• For long background subagents, check the working directory or logs directly with Bash or Read rather than re-running the whole subagent again out of impatience.

If a subagent seems to be doing far more work than its prompt implied, tighten the prompt. A vague brief like "check this code for problems" invites an open-ended, slow investigation. A specific brief like "check this diff for SQL injection and hardcoded credentials only" bounds the work and speeds up the parallel batch overall, since your total time is gated by the slowest branch.

Pitfalls When Running Subagents in Parallel

Shared file writes. Two subagents editing the same file at the same time is a race condition, not parallelism. If two tasks need to touch the same file, either serialize those two specifically or have one subagent do the writing based on both sets of findings.

Over-broad tool access. Giving every subagent full Bash and Write access "just in case" means a misbehaving prompt in one branch can affect files another branch is relying on. Scope tools per agent to what that specific job needs.

Treating dependent steps as independent. "Write the migration, then run it, then verify the schema" is a strict sequence. Trying to parallelize it produces a subagent verifying a schema that hasn't been migrated yet. Only fan out steps that do not need each other's output.

No summarization step. Three subagents returning three separate, unmerged reports is not a finished task. Always have the parent agent read all the results and produce one coherent answer, especially when findings overlap or contradict.

Ignoring cost and context budget. Every subagent call carries its own token cost. Fanning out fifty subagents for a task that five could handle is not free parallelism, it is fifty separate context windows worth of overhead. Batch related sub-tasks into one subagent when they are small enough to share context usefully.

Polling background subagents. As covered above, checking in constantly on a background subagent defeats the purpose of running it in the background. Set it going, do something else, and let the completion notification do its job.

FAQ

What is the difference between a Claude Code subagent and just asking the main agent to do more? A subagent has its own isolated context window and, usually, a restricted toolset and a fixed system prompt describing its one job. The main agent stays clean because it only receives the subagent's final summary, not every file it read or command it ran along the way. This keeps long sessions from degrading as unrelated exploration piles up in context.

How many subagents can I run in parallel at once? There is no fixed number baked into the workflow itself; the practical limit is how many genuinely independent branches your task actually has, plus your tolerance for combined token cost. Two or three focused subagents on real independent work is far more useful than a dozen on trivial ones.

Do parallel subagents share context with each other? No. Each subagent only sees what you put in its prompt. If one subagent needs information another subagent discovered, that information has to pass through the parent, either by running them sequentially or by dispatching the second one after the first returns.

Can a subagent spawn its own subagents? Some setups allow nested delegation, but it is usually better to keep an agent that is itself a delegated subagent focused on doing its assigned work directly rather than re-delegating. Deep nesting makes failures hard to trace and adds latency without adding much value for most tasks.

Should I always use `background` mode for long-running subagents? Use background mode when the subagent's result does not block your very next action. If you need the answer before you can decide what to do next, foreground dispatch and waiting is simpler and avoids the discipline problem of remembering to check back in.

How do I stop a parallel fan-out from turning into a mess of unmerged results? Always close the loop with a synthesis step. After the parallel subagents return, have the parent agent read every result, resolve any conflicts, and produce a single combined report before treating the task as done.