[DOCS] Subagent documentation omits the concurrent-running subagent cap
Documentation Type
Missing documentation (feature not documented)
Documentation Location
https://code.claude.com/docs/en/sub-agents
Section/Topic
Concurrency limits for background and foreground subagents
Current Documentation
The current subagent limits section says:
By default, Claude can spawn at most 200 subagents per session. To raise the limit, set CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION to any positive whole number; there is no upper bound, but the limit can't be turned off.
The environment-variable reference documents CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION and separately lists CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY, but it does not list CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS.
What's Wrong or Missing?
Claude Code 2.1.217 adds a cap on concurrently running subagents, with a default of 20 and an override named CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. The current documentation describes only the cumulative per-session spawn limit of 200. It does not explain that a session can have more total subagent spawns over time while only a bounded number run at once, nor how the new cap interacts with background agents, workflows, or CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY.
Without this distinction, users cannot predict why a fan-out request pauses or denies new background work even when the session has not reached its 200-subagent lifetime limit.
Suggested Improvement
Add a “Concurrent subagent limit” subsection to the subagents page and add CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS to the environment-variable reference. Document the default of 20, the accepted override format and whether the value can be disabled, what happens when the cap is reached, and how it differs from the per-session spawn limit and the general tool-use concurrency setting. Include a short example for organizations that need to reduce fan-out.
Impact
Medium - Makes feature difficult to understand
Additional Context
Affected Pages:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/sub-agents | 851-861 | Documents the 200-per-session limit but not the 20-concurrent limit |
| https://code.claude.com/docs/en/env-vars | Environment variables reference | CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS is absent; nearby concurrency variables can be confused with it |
| https://code.claude.com/docs/en/agent-view | Background agents and session fan-out | Needs a cross-reference explaining how concurrent work is capped |
Version: Claude Code 2.1.217.
Total scope: 3 pages should distinguish the new concurrency cap from existing subagent limits.
3 Comments
Good catch on the undocumented concurrent cap. The interaction between
CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION(cumulative) andCLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS(in-flight at once) is easy to miss because they govern two completely different resources.One practical note that may save someone a debugging session: if you hit the concurrent cap mid-workflow, the behavior depends on whether the orchestrator is using the Task tool with
run_in_background: true. Foreground tasks queue and wait; background tasks can drop their wake notification silently (tracked in #78338), which looks identical to a hung agent from the dispatcher's side.Until the docs catch up, the env var trio worth pinning together:
CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION- total spawns (default 200)CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS- in-flight at once (default 20 since v2.1.217)CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY- tool calls within a single agent (separate axis)(Disclosure: I build Claudiverse, a GTM polling runner that manages long-running Claude Code agent fleets - we hit this exact interaction when the concurrent cap landed.)
Thanks — this is documented. The subagents page has a "Concurrent subagent limit" section covering the default of 20 running subagents, the
Concurrent subagent limit reachederror, how it differs from the depth limit, and theCLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSoverride, which is also listed in the environment-variable reference:Closing as documented.
🤖 Generated with Claude Code
This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.