How do I run multiple research subagents in parallel?

A subagent is a fresh Claude session that runs your prompt in isolation, reads files, and hands back one summary message that the parent receives as a tool result. Parallelism is powerful and easy to misuse: the parent only sees the summary, not the trail.

Fire several in parallel

Ask for parallel subagents in plain English in one user turn. Claude Code dispatches them concurrently:

Research three things in parallel using separate subagents, one per task. For each, return file:line evidence plus a 5-bullet summary.

1. Find the welcome email template. Report the file path, the 5 lines around the H1 string, and the function that renders it. Stack: TypeScript + React Email.
2. Find the login rate-limit configuration. Report file:line and the numeric value. Stack: express-rate-limit.
3. Find any feature flag that gates the new checkout flow. Report flag name, default, and every file that consumes it. Flags live in src/flags/.

Three subagents start, do the search, and return one summary each. The parent reads them and synthesizes. You spent one user message, three isolated contexts, and a few seconds, instead of three sequential searches in your own context.

If you are building on the Agent SDK in your own application, you do not emit Agent tool calls directly: you provide the model with the Agent tool and (optionally) named agent definitions, and the model decides to invoke them. To get parallelism, write the prompt the same way you would in Claude Code: explicitly ask for multiple independent subagents in one turn.

The four checks before you delegate

Use a subagent when all four apply:

1. Noisy lookup. The work involves reading dozens of files or browsing a wide tree. None of that belongs in parent context.
2. Independent of other work in this turn. Subagents cannot wait on each other’s output. If steps depend, run them sequentially.
3. One round-trip is enough. Plan for the subagent to return one summary and exit; resumable subagents exist under agent teams (via SendMessage), but do not design ordinary research prompts around that. If “find the bug” might lead to “okay, why?” do the work inline.
4. You can specify the deliverable. Subagents do not automatically receive the full parent conversation; the parent assembles the task prompt and sends only that. Specify what to find, what shape the answer should take, what to ignore, and any relevant context the subagent will not figure out on its own.

If any one is shaky, do the work inline.

Footguns

The parent receives the summary, not the trail. A subagent that reads ten files and returns “the JWT is minted in src/auth/token.ts:47” gives you the answer, not the path of inferences. The parent’s live context never receives the intermediate reads. The transcript persists on disk under ~/.claude/projects/{project}/{sessionId}/subagents/, so you can grep it after the fact, but during the session you have nothing to follow up against. Defense: ask for the evidence in the prompt. “Report the function, the 5 lines around it, and any other file you considered before this one.” Force the subagent to surface what you would want for a follow-up.

Each subagent burns its own full context window. Ten parallel subagents means ten 200K contexts under the hood. That is fine when each prompt is narrow; it is expensive when each one starts with “read the entire codebase first.” Keep subagent prompts scoped (specific directories, specific filenames, specific symbols). Parent context is the one you most need to protect, but a subagent’s context is not free.

Prompt drift across parallel runs produces incomparable reports. Three subagents that look almost identical in your message (“find auth in service X”, “find auth in service Y”, “find auth in service Z”) will return divergent shapes if the wording diverges between them. One reports file paths and line numbers; the second reports prose; the third describes architecture. Aggregating them is then your problem. Defense: write a template prompt once, copy-paste it three times, and change only the service name. Identical prompts produce comparably-shaped output.

Sequential beats parallel whenever step 2 needs step 1’s answer. “Find the rate-limit config” and then “find the test that mocks the middleware that uses it” cannot run in parallel; you do not have the middleware name until step 1 returns. Running them in parallel forces the second subagent to redo step 1’s search, doubles cost, and risks inconsistent answers if the two subagents pick different files. Run sequentially when later questions depend on earlier ones; run in parallel only when they truly do not.

A subagent is not a second opinion if it has seen your reasoning. The reason a code-review subagent gives independent feedback is precisely that the parent’s conversation never reaches it. The moment you write “I think the bug is in auth.ts, please verify”, you have biased the fresh session. Either hand it the diff and the symptom (no theory), or stop calling it a second opinion.

When NOT to use a subagent

• You will iterate on the answer. One round-trip and exit. If the next move is “okay, dig deeper”, do the work inline so the context survives the follow-up.
• The task lives in your head, not the codebase. Architecture decisions, “should we use X or Y”, scope tradeoffs: these need the full conversation, not a fresh session that has not heard any of it.
• The work fits inline in 30 seconds. A glob, a grep, a single-file read. The Agent-tool overhead and the prompt-writing tax do not pay for themselves on a task you would have finished while writing the subagent prompt.
• You need the tool output, not just the conclusion. If you wanted the actual diff or actual file contents in your context, run the read in the parent. Subagents return summaries by design.
• The steps depend on each other. Sequence them inline. Parallel subagents that are not actually independent waste tokens and can produce contradictory answers if they pick different files for an ambiguous step.