How to Use Claude Code Subagents for Parallel Research

Subagents are the single feature that changes how much work you can get through Claude Code per hour. Used right, a three-subagent fan-out completes cross-codebase research in 90 seconds that a linear pass would spend 7–10 minutes on. Used wrong, you burn tokens and end up with three redundant reports. This is the operating manual.

TL;DR

• A subagent is a fresh Claude conversation with its own context window, started by your main agent to do a scoped task.
• Use subagents when the work is genuinely independent (multiple files, multiple topics, multiple codebases).
• Do not use subagents when the work is sequential (each step needs the previous result).
• The Explore subagent is the right default for search/read tasks; it has no write tools and returns a summary.
• Spawn up to 3 in parallel in a single message; more produces diminishing returns and noisy context.
• The parent does not see the subagent's internal tool calls — only the final summary. Write the prompt so the summary is the thing you need.

What exactly is a subagent

When your main Claude Code session calls the Agent tool, it spawns a new Claude instance. That instance:

1. Gets its own system prompt (defined by the subagent type — e.g., Explore, Plan, general-purpose).
2. Starts with an empty context window.
3. Has its own tool access, possibly narrower than the parent's.
4. Runs to completion independently.
5. Returns a single message to the parent.

The parent sees the return message and nothing else — not the subagent's intermediate reads, greps, or reasoning. This is a feature. Your parent conversation stays clean.

The three subagent types worth knowing

As of April 2026, Claude Code ships with a handful of built-in subagents plus any project- or user-defined ones. The three you will use 80% of the time:

Explore

Fast search and read agent. No Edit, Write, or other mutation tools. Ideal for:

• Finding where a function or pattern is defined
• Answering "how does X work in this codebase"
• Surveying multiple areas of a codebase in parallel

Plan

Software architect agent. Returns a step-by-step implementation plan with critical files and architectural tradeoffs. Use when you need a design pass before coding.

general-purpose

Full tool access. Use for multi-step tasks that require both reading and writing. More expensive because it carries the full toolset into its context.

You can also define custom subagents — a .claude/agents/*.md file with a description and tool list. I have a design-system-extractor agent, a code-reviewer agent, and a security-auditor agent. Each is narrow enough to do one thing well.

When subagents actually help

The rule is: subagents help when the work is independent and parallelizable. Three cases where they pay off handsomely, and three where they don't.

Subagents help:

Case A — Cross-codebase survey. "How do Stripe, Polar, and Lemonsqueezy each handle webhook signature verification in our codebase?" Three subagents, one per integration, run in parallel. A linear sweep of the same question takes 3-4x longer because each probe blocks the next.

Case B — Independent file reads. "Read these 8 migration files and tell me if any of them drop columns unsafely." Two or three subagents, each handling a subset, run concurrently.

Case C — Broad-to-narrow research. The parent needs a shallow answer across many areas before deciding where to go deep. One subagent per area, all parallel, and the parent integrates the findings.

Subagents do NOT help:

Case D — Sequential dependency. "Refactor the auth module, then update the tests, then update the docs." Each step needs the previous step's output. Subagents here just add overhead.

Case E — Single-file work. Editing one file with one context. The main agent is already scoped correctly.

Case F — Tight feedback loops. Iterating on a single implementation with the user. Subagents break the loop.

The parallel fan-out pattern

The single most useful pattern:

User question: "How does this codebase handle [X] across [A, B, C]?"

Main agent → spawns in parallel:
  - Subagent 1: investigate A
  - Subagent 2: investigate B
  - Subagent 3: investigate C

Main agent → integrates three summaries → delivers unified answer.

To get the parallelism, the parent must emit multiple Agent tool calls in a single message. Emitting them one at a time serializes them. This is the most common user mistake.

In practice, inside Claude Code, prompt the main agent explicitly:

"Run three Explore subagents in parallel to investigate A, B, and C independently."

The word "in parallel" signals intent. Without it, the agent will sometimes serialize out of habit.

The quality-of-prompt matters more than the fan-out

A subagent cannot ask you follow-up questions mid-run. Whatever instructions it starts with are what it has to go on. This makes prompt discipline twice as important as in the main conversation.

Checklist for a good subagent prompt:

1. State the goal, not the steps. "Report whether any migrations drop columns unsafely" is better than "run grep for DROP COLUMN; open each file; check context."
2. Give it the files or area. "In apps/api/migrations/" beats "somewhere in the codebase."
3. Bound the response size. "Under 200 words" or "bulleted list only" prevents the return message from inflating.
4. Describe the shape of the answer. "For each file: filename, verdict (safe/unsafe), one-sentence reason." The subagent will then produce a clean table you can scan.
5. Never ask a subagent to decide whether to edit. Scope subagents to research, not implementation. Let the parent conversation decide on changes.

Measured cost and time tradeoffs

I ran a side-by-side benchmark on a 40K-line TypeScript monorepo. Task: identify all places where we log user input without redaction.

Three parallel subagents reduced wall time by ~75% and improved accuracy. Bumping to five parallel agents did not meaningfully help wall time (we were already at the slowest subagent's latency floor) and added 27% more tokens. The sweet spot for this task was three.

The general heuristic from this and similar benchmarks: parallel up to 3 usually wins; beyond 3 is diminishing. The only exception is when each subagent is investigating a truly separate codebase (not just a separate directory) — in that case, 4-5 can pay off because the per-agent contexts are very different.

Anti-patterns to avoid

Anti-pattern 1 — The redundant fan-out

You ask three subagents the same question with slightly different wording, then compare answers. This only works for adversarial reliability testing (evals). For real work, pick one.

Anti-pattern 2 — The micro-task subagent

Spawning a subagent to read a single file or run a single grep. The tool invocation overhead exceeds the savings. If the task is narrower than "investigate this subsystem," do it in the main agent.

Anti-pattern 3 — The "plan then execute" pair where the execute is ambiguous

A parent spawns a Plan subagent, gets a plan, and then asks "based on the plan, implement it" — either as another subagent or itself. This hands synthesis off and typically produces drift because the plan was written by a different agent. Read the plan yourself, then drive the implementation from your own understanding.

Anti-pattern 4 — Subagents as delegation to avoid thinking

If you find yourself spawning subagents to avoid having to hold the problem in your own head, you will lose the thread. Subagents are a force multiplier for understood tasks, not a substitute for understanding.

Custom subagents: when they are worth it

If you find yourself writing the same 10-line prompt prefix for Explore tasks three times a week, extract it into a custom subagent. A minimal example:

---
name: security-audit
description: Reviews a specific area of code for OWASP top 10 issues.
  Reports file/line + issue category + suggested fix.
tools: Read, Glob, Grep
---

You are a security auditor. When invoked, you must:
1. Read the code in the area provided.
2. Check against OWASP top 10 (injection, broken access control, etc.).
3. Return a markdown table: file, line, category, severity, fix suggestion.
4. If no issues found, return "No issues in scope."

Do not edit files. Do not guess.

Save as .claude/agents/security-audit.md. Now you can invoke it:

Agent(subagent_type="security-audit", description="Audit auth module", prompt="Audit src/auth/ for OWASP top 10.")

The prompt savings and consistency pay for themselves after ~5 uses.

Practical recipes

Recipe 1 — Cross-codebase "how do we handle X"

Run three Explore subagents in parallel:
  1. In apps/api/, how do we handle rate limiting?
  2. In apps/web/, how do we handle rate limiting?
  3. In packages/shared/, how do we handle rate limiting?

Each returns: files touched, approach summary, invariants. I will reconcile.

Recipe 2 — Library evaluation

Run three Explore subagents in parallel to evaluate replacing Zod with:
  1. Valibot — check API surface we use; identify gaps
  2. Arktype — check API surface we use; identify gaps
  3. io-ts — check API surface we use; identify gaps

Each returns: compatibility report, estimated migration effort (lines), risks.

Recipe 3 — Dependency audit

Run two Explore subagents in parallel:
  1. Read package.json and all imports; list npm deps not actually imported.
  2. Read all imports and check against package.json; list imports with no dep entry.

Each returns: list only.

Recipe 4 — Pre-refactor reconnaissance

Run three Explore subagents in parallel before refactoring the billing module:
  1. Map all callers of billing functions (inbound dependencies).
  2. Map all services billing functions call (outbound dependencies).
  3. List all tests that touch billing paths.

I will use the three reports to plan the refactor scope.

FAQ

Can a subagent spawn its own subagents? Yes, general-purpose subagents can call Agent. But nested spawning makes debugging painful and tokens expensive. Avoid unless genuinely necessary.

Do subagents share context with the parent? No. Each subagent starts fresh. Whatever the parent knows, you must pass to the subagent in the prompt.

How do I give a subagent access to specific files only? Either in the prompt ("only read files under src/auth/") or in a custom subagent's system prompt. There is no hard filesystem sandbox per subagent; it's by instruction.

Can subagents modify files? Depends on the subagent type's tool access. Explore cannot. general-purpose can. Custom subagents are constrained by their tools: field.

How do I pass large amounts of input to a subagent? Put it in the prompt. There is no file attachment mechanism. If the input is very large, have the subagent read the file itself via its Read tool and pass the path instead.

What's the cost of a subagent? Same model pricing as a regular call, counted separately. A three-subagent fan-out costs roughly 3x a single call in tokens, but buys you ~3x wall-clock speedup on parallelizable work.

Should I use subagents from the Claude API (not Claude Code)? The same fan-out pattern works via the Agent SDK. You manage the orchestration yourself. The trade-off is you get full control; the lift is you have to write the plumbing.

Summary

Subagents are a parallelism primitive. They pay off when the work is genuinely independent, the fan-out is 2-3 wide, and each subagent has a clear scope and a bounded return shape. Use the Explore subagent as your default for research; reach for Plan when a design pass helps; build custom subagents for tasks you run repeatedly. Do not use subagents to avoid thinking — use them to parallelize thought you have already structured.