What is a Claude Code subagent?

A subagent is a child Claude process spawned via the Task tool, with its own context window separate from the parent. Subagents see only the prompt the parent gives them — no conversation history, no inherited tools by default (unless explicitly passed). They return a single result. Best for: tasks that benefit from a 'fresh context' (code review, audit, research) and for parallelizing independent work.

When should I NOT use a subagent?

Three cases. (1) The task is single-step and the parent can do it in one tool call — spawning a subagent costs latency. (2) The task requires conversational context the subagent doesn't have. (3) The task needs to modify the parent's state directly. Subagents are isolated by design; if you need shared state, use the parent.

Can subagents call other subagents?

Yes, but the orchestration overhead compounds. Three levels deep and you're paying for context tokens at each level. We cap at one level of subagent recursion unless we have a specific reason to nest deeper, and we never go past two.

How is a subagent different from a skill?

A skill is a folder of instructions Claude loads on demand into the current session — it changes how the current agent behaves. A subagent is a separate Claude process — it does its own work, returns one result, and disappears. Skills and subagents compose: you can spawn a subagent and have it load a skill.

How do I brief a subagent effectively?

Four ingredients: (1) exact file paths to touch, (2) a quality bar (what 'done' means), (3) a validation command (how the subagent proves it's done), (4) the return format. Subagents do not have your conversation context. 'Figure out what to do' is never acceptable — you have to do the planning the subagent will execute.

What's the parallelism limit?

Claude Code supports concurrent subagent spawns but the rate-limit budget is shared with the parent. In practice, 3-5 concurrent subagents is the sweet spot. Beyond that you hit either the rate limit or coordination overhead — collecting and merging results from 10 subagents is its own engineering problem.

When to Parallelize Claude Code Subagents (Decision Tree)

The subagent — a child Claude process spawned via the Task tool — is one of the most powerful features in Claude Code and one of the most misused. The misuse pattern is recognizable: a developer hears "subagents work in parallel" and starts spawning them for every task, ending up with a session that costs 4x what it should and produces output worse than a single-pass conversation would have.

This page is the decision tree. When does a subagent help? When does it hurt? What does briefing one look like in practice? The answers come from auditing Anthropic's own docs, Obra's Superpowers framework (which is built around subagent orchestration), wshobson's agents repository, and a year of running multi-agent setups in production.

What a subagent actually is

A subagent is a separate Claude process spawned by the parent session via the Task tool. Three properties define its behavior:

Fresh context. The subagent starts with no conversation history. It sees only the prompt the parent gave it. This is the feature that makes subagents valuable — they have no in-context bias from the parent's earlier work. Independent tool set. The subagent's available tools are determined by what the parent passes (or by the subagent's own configuration if it's a named subagent). The parent doesn't share its loaded skills automatically. Single return. The subagent does its work, returns one result, and disappears. There is no back-and-forth conversation with the parent unless the parent spawns another subagent.

This is materially different from a skill, which modifies the current session's behavior. Skills and subagents compose — a subagent can load a skill — but they are different primitives.

When to use a subagent

Three patterns where subagents reliably outperform inline work.

Pattern 1 — fresh-context review

The parent has written code. You want a review. If you ask the parent to review its own code, you get post-hoc rationalization — the model justifies the choices it just made. If you spawn a subagent with the file paths and a review prompt, the subagent has no skin in the game and finds things the parent missed.

This is the canonical subagent use case. Obra's Superpowers framework makes it the default for any non-trivial change. The win is measurable — in our testing, a subagent code review catches roughly twice as many real issues as an inline review of the same change.

Brief shape:

Review the changes in src/auth/oauth.ts (commit abc1234).
Focus: race conditions on token refresh, missing CSRF handling,
unsafe redirect URL validation.
Pass: name specific line numbers for each issue with severity tags
(P0/P1/P2). Return null if nothing found.

Notice what's in the brief: file path, scope, quality bar, return format. Notice what's not: "look for problems" — too vague.

Pattern 2 — parallel independent work

You have N tasks that don't share state. Refactoring 5 files that each need similar treatment. Researching 8 vendors in parallel. Writing tests for 6 functions that don't interact. A subagent per task runs them concurrently; the wall-clock time is set by the slowest, not the sum.

When this works: the tasks are genuinely independent. No shared mutable state. No ordering dependency. Each subagent can succeed or fail on its own without affecting the others. When this fails: the tasks are coupled. Refactoring 5 files where each file's refactor depends on the other four lands in merge hell when the subagents return. Use sequential work for coupled changes.

Pattern 3 — long-running research

Autoresearch ports (uditgoenka, ARIS) use subagents this way at scale. A research question gets decomposed into sub-questions; each sub-question becomes a subagent task; the parent synthesizes the results.

The win here is depth — a subagent can spend 20-30 minutes on one sub-question without bloating the parent's context. The parent stays light; the subagent does the heavy reading.

/topic/autoresearch covers this pattern end-to-end.

When NOT to use a subagent

Three patterns where subagents lose.

Anti-pattern 1 — single-step work

The parent could call the tool directly. Wrapping a single Read or Bash call in a subagent adds 5-15 seconds of orchestration overhead with zero benefit. The "spawn a subagent for everything" anti-pattern is the most common.

The rule: if the task is "read this file and tell me X," do it inline. If the task is "audit this directory and tell me everything," spawn a subagent.

Anti-pattern 2 — context-dependent work

The task requires the parent's conversation history. "Apply the same pattern we discussed earlier" doesn't work as a subagent brief — the subagent has no "earlier." Either inline the work, or pass enough context in the brief that the subagent doesn't need history.

Anti-pattern 3 — coordination-heavy work

The task needs the subagent to ask follow-up questions, coordinate with other subagents in flight, or modify the parent's state mid-execution. Subagents are isolated by design. If you need coordination, you need a different primitive (a hook, a shared file in the working directory, or sequential work in the parent).

The decision tree

Given a task, ask in this order:

Can the parent do this in one tool call? Yes → inline.
Does the task need conversation history the subagent won't have? Yes → inline, or restructure the brief.
Is the task independent of N other tasks? Yes and there are 2+ tasks → spawn parallel subagents.
Does the task benefit from a fresh context (code review, audit, second opinion)? Yes → spawn a subagent.
Will the task take 10+ minutes and bloat the parent context? Yes → spawn a subagent.

If none of these match, default to inline. The subagent overhead is real; only pay it when one of the above conditions is true.

How to brief a subagent

The single most important discipline is: the subagent does not have your context. Anything you don't tell it explicitly, it doesn't know. A brief that says "review this code" is a brief that's missing the file paths, the quality bar, the focus areas, and the return format.

Four ingredients, every time:

1. Exact file paths to touch. Absolute paths preferred. src/auth/oauth.ts:115-159 is better than "the auth code." 2. Quality bar. What does "done" mean? "Find all P0/P1 security issues" is a quality bar. "Make it better" is not. 3. Validation command. How will the subagent know it succeeded? "Run npm test and confirm exit 0" is a validation command. The subagent's claim "I'm done" is not. 4. Return format. What should the subagent return? A list? A diff? A markdown report with specific sections? Constrain the format or you'll spend time re-formatting the output.

Bad brief:

"Audit our authentication code for security issues."

Good brief:

"Audit src/auth/ for: missing CSRF on state-changing endpoints, OAuth redirect validation gaps, race conditions on token refresh, missing rate limits on login endpoints. Read every .ts file in src/auth/. Run npm test and confirm exit 0 before returning. Return a markdown report with sections P0/P1/P2, each finding citing file:line, with a one-sentence proposed fix. If nothing found in a section, write 'none' — do not omit the section."

The good brief is longer. It is also dramatically more likely to produce useful output, and the time spent writing it is recovered 5x in the quality of what comes back.

Concurrency limits

Claude Code supports concurrent subagent spawns, but the rate-limit budget is shared with the parent session. Practical limits:

1-3 concurrent subagents: safe everywhere, no rate-limit risk
3-5 concurrent subagents: sweet spot for parallel independent work
5-10 concurrent subagents: possible but rate-limit-bounded
10+ concurrent subagents: "24 simultaneous agents" demos exist (HN 47099597) but coordination overhead dominates real productivity gains

If you find yourself wanting 10+ concurrent subagents, you probably want a different tool — a queue (BullMQ, Inngest) or a batch job runner, not Claude Code orchestration.

Subagents and the multi-tool ecosystem

The subagent primitive is Claude-Code-specific. AGENTS.md-compatible tools (Cursor, Codex CLI, Gemini CLI, Aider, Windsurf, Zed, Warp, RooCode) have their own analogs — Cursor's Composer can dispatch parallel work, Codex CLI has background tasks — but the implementations differ.

If you're shipping a skill or ruleset that depends on subagents, document it as Claude-Code-specific. Cross-tool portability is a separate concern; see /topic/cross-tool-skills (when it exists in your tree).

Where this fails

Subagent quality is bounded by the brief quality. A vague brief produces vague output, in the subagent or out of it. Most teams' first subagent attempt fails because the brief is "figure out what to do" — the parent did not do its own planning before delegating. Cost compounds. Each subagent's context, prompt, and output costs tokens. A 5-subagent parallel workflow on Opus 4.7 can cost $2-5 per run. Set budget caps in the parent's tooling if you're paying for tokens. Coordination is hard. Merging output from 5 subagents that each refactored a related file is a manual reconciliation task. The parent does the merging; if the subagents made incompatible choices, the merge fails. Test on small parallel runs before scaling up. The "fresh context" property cuts both ways. A subagent that doesn't know about the project's conventions, style guide, or recent decisions will produce output that doesn't fit. Pass the relevant context in the brief — either inline or as a file path the subagent can read.

Where this fits in the bigger pattern

Subagents are one piece of the agentic-engineering toolkit. The full pattern (per Obra's Superpowers and Karpathy's autoresearch) is: a planning loop in the parent, parallel subagent dispatch for sub-tasks, persistent notes to disk for recovery, and explicit review gates between phases. Subagents are the parallelism primitive. Skills are the capability primitive. Hooks are the enforcement primitive. CLAUDE.md and AGENTS.md are the context primitive. Each has a place; over-using any of them is the failure mode.

Sources

Anthropic. "Sub-agents documentation". The Task tool, agent configuration, fresh-context semantics.
Anthropic. "Agent teams". Team-level subagent patterns.
Obra (Jesse Vincent). superpowers repository. Subagent-driven development as a methodology.
wshobson. agents repository. Production multi-agent orchestration examples.
VoltAgent. awesome-claude-code-subagents. 100+ subagent definitions, depth corpus.
HN 47099597. "24 Simultaneous Claude Code agents on local hardware". The scale-theater example.
HN 46990733. "Show HN: 20+ Claude Code agents coordinating on real work". Real multi-agent setup.
Daniel Miessler. "When to use skills vs commands vs agents". The three-primitive decision.