How many subagents can Claude Code run at once (and what it costs you)

Claude Code stops you at 20 subagents running at once by default - spawn a 21st with the Agent tool while that many are already active and it fails outright with Concurrent subagent limit reached. That number is real and documented, but almost nobody who hits a wall running subagents in parallel is anywhere near it. The wall that actually stops you is the context each finished subagent hands back to your main conversation, and that ceiling can arrive at 5 subagents just as easily as at 20.

The actual number: 20 concurrent subagents by default

Claude Code's subagent documentation states the concurrency limit plainly: by default, when 20 subagents are running in a session, spawning another one with the Agent tool fails with Concurrent subagent limit reached, and the error explicitly tells Claude not to retry. Spawning succeeds again as soon as the running count drops below 20. This requires Claude Code v2.1.217 or later; earlier versions didn't enforce a concurrency cap at all.

You can move the number in either direction. Setting CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS to any positive whole number in settings.json raises or lowers the cap:

{
  "env": {
    "CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS": "10"
  }
}

One documented exception: sessions with ultracode active aren't held to this limit at all. And the limit only blocks subagents Claude spawns through the Agent tool - an in-session fork started with /subtask takes a running slot without ever being blocked by the cap, and resuming a subagent that already finished takes a fresh slot without checking the limit either, so a resume can push the running count past 20.

The depth limit is a different number, and it's easy to conflate the two

"How many can run at once" and "how many layers deep can they go" sound like the same question. They're governed by two separate settings, and the docs are explicit that they don't interact.

| | Concurrency limit | Depth limit | | --- | --- | --- | | Env var | CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS | CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH | | Default | 20 | 3 | | Governs | How many subagents can be running at the same moment | How many layers a subagent can spawn subagents of its own | | What happens at the limit | The next spawn attempt fails with Concurrent subagent limit reached | The Agent tool is withheld from every subagent at the limit except a fork, so it does the work itself and returns one summary |

The depth default has moved before, which matters if you're reading an older thread about it: Claude Code v2.1.172 through v2.1.216 allowed nesting up to five layers deep with no way to change it, v2.1.217 through v2.1.218 dropped the default to one layer (nesting off unless you raised it), and v2.1.219 raised it back to three, which is what ships today. Setting CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH to 1 turns nesting off entirely; setting it to 2 caps it one layer short of the current default.

Why you'll hit a different ceiling long before 20

Every subagent pays a fixed cost the moment it starts, before it reads a single file or runs a single command: its own system prompt and frontmatter, the CLAUDE.md hierarchy your session already loaded (Explore and Plan are the two built-in subagents that skip this), and a git status snapshot unless you've turned that off. None of it is shared or cached across subagents - each one pays in full, independently, every time.

This project measured one real example: a subagent definition pulled verbatim from Anthropic's own docs, run through this project's own token estimator, comes to 216 tokens for the system prompt and frontmatter alone (the same number cited in Claude Code subagents vs Skills). That's the floor, before the CLAUDE.md hierarchy or the actual task. Multiply it by how many you fan out at once and the fixed cost alone climbs fast: 5 subagents starting at once is roughly 1,080 tokens of pure startup tax before any of them does anything, 10 is 2,160, 20 is 4,320. Your own CLAUDE.md hierarchy rides on top of that per subagent too - a longer file multiplies the same way tool definitions do, so a CLAUDE.md that's expensive once becomes expensive N times over the moment you fan out.

What a wide fan-out actually returns to your main conversation

The startup tax is the smaller half. Claude Code's own guidance on running parallel research warns directly that when subagents complete, their results return to your main conversation, and running many subagents that each return detailed results can consume significant context. A subagent's internal exploration, file reads, and false starts stay isolated in its own window - that's the entire point of delegating - but the summary it hands back lands in your main thread and stays there for the rest of the session, recharged as a cache read on every later turn.

Fan out 10 subagents against 10 different modules and ask each for a thorough writeup, and you've traded one large exploration for 10 medium-sized ones that all land in the same place. The isolation helped during each subagent's own work; it does nothing for what comes back. This is the actual mechanism behind "running several sessions or subagents at once multiplies token usage," which the docs state as a blanket warning without putting a number on it, because the number depends entirely on how much each subagent chooses to report back.

When 20 genuinely isn't enough: agent teams and dynamic workflows

If the concurrency cap is the thing actually stopping you, subagents were the wrong tool for the job before you hit it. Claude Code's docs point at two purpose-built alternatives for work that outgrows a handful of subagents in one session:

• Agent teams (experimental, disabled by default) give each teammate its own independent context instead of routing every result back through one conversation, with a shared task list and direct messaging between teammates.
• Dynamic workflows run a script that spawns many subagents and cross-checks their results against each other, built for work too big to coordinate one turn at a time - a codebase-wide audit, a migration across hundreds of files, research that needs verifying from more than one angle. The /batch skill is a packaged version of this: it splits one large change into 5 to 30 worktree-isolated subagents that each open their own pull request.

Both exist specifically because routing everything back through one main conversation, which is what plain subagents do, stops scaling before the concurrency limit ever becomes the binding constraint.

How to tell you've gone too wide

• You're fanning out more than 4 or 5 subagents for one question. Below that, the returned summaries are usually small enough to absorb. Above it, check what each one is actually being asked to return.
• You're asking each subagent for "a thorough writeup" instead of a specific, bounded answer. The isolation only pays off if the returned summary is small relative to what got explored - a subagent that reports back everything it found isolated nothing.
• You're nesting subagents that spawn subagents that spawn subagents. At three layers deep by default, that's already close to the depth limit, and each layer's summary has to pass back up through the one above it.
• Your session's context usage jumps sharply right after a batch of subagents reports in, not during the delegation itself. That's the signature of returned-result cost, not startup tax - the fix is tightening what you ask each subagent to report, not spawning fewer of them.

When this doesn't apply

None of this matters if you're only ever running one or two subagents at a time - the fixed startup cost and the returned-result cost are both small enough to ignore below that. It also doesn't apply inside agent teams or dynamic workflows, which follow their own limits and their own cost shape, not the plain-subagent concurrency cap this article covers. And a forked subagent (/subtask) sidesteps the startup-tax math entirely, since it inherits the parent conversation's system prompt and reuses its prompt cache instead of paying fresh.

FAQ

• What's the actual limit on how many subagents Claude Code can run at once? 20 by default, set by CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. Spawning a 21st while 20 are already running fails with Concurrent subagent limit reached until the count drops. Requires Claude Code v2.1.217 or later.
• Can I raise or lower that limit? Yes. Set CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS to any positive whole number in settings.json. Sessions with ultracode active aren't held to the limit at all.
• Is the concurrency limit the same as the nesting depth limit? No, they're two different settings. CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS (default 20) caps how many subagents run at the same moment; CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH (default 3) caps how many layers deep a subagent can spawn subagents of its own.
• Will I actually hit the concurrency limit in normal use? Rarely. Most sessions run out of usable context from returned subagent results long before they'd spawn a 20th subagent at once.
• Does resuming a finished subagent count against the concurrency limit? No. Resuming a subagent that already finished takes a fresh running slot without checking the limit, so a resume can push the count past 20.
• What should I use instead of plain subagents if I need more sustained parallelism? Agent teams (experimental, disabled by default) or dynamic workflows, both built for work that outgrows what routing every result through one main conversation can handle.

None of the math above tells you what your own sessions are actually spending on subagent fan-out - it's built from one measured example subagent and a documented default, not your transcripts. The free scan reads your real Claude Code session history and shows what your own subagent calls are costing you, and the subagent cost calculator compares spawning N subagents against doing the same work in one session using this same measured overhead number.

Made by Neo

UsageCut by ClockedCode - not affiliated with Anthropic. The figures on this page are measured on real Claude Code sessions and labeled measured or estimated where it matters.