Feature Request: Configurable concurrent subagent limit in workflows

Found 3 possible duplicate issues:

1. https://github.com/anthropics/claude-code/issues/15487
2. https://github.com/anthropics/claude-code/issues/58078
3. https://github.com/anthropics/claude-code/issues/25714

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

Good use case — the min(16, cpu_cores - 2) cap bites anyone running research sweeps or large-scale review pipelines.

Worth noting a related constraint: even with a higher concurrency limit, the coordination burden grows non-linearly. With 8–16 agents you start needing something to track which agents completed, retry the ones that stalled, and keep a lock on shared state so two parallel reviewers don't clobber the same file. That bookkeeping usually ends up as custom shell glue or a Makefile sitting around the workflow.

We ran into this exact problem building Claudiverse — a polling coordinator that schedules agent sessions and mediates their state. The max-concurrency limit is one layer; the session lifecycle management (heartbeat, stale-lock cleanup, idempotent retry) is the other. If you're hitting the hard cap on a 10-core machine, you might also be 20 minutes away from needing that second layer.

Would be curious what scale you're targeting — 32 concurrent agents on a single machine or spread across nodes?

Adding a data point from the opposite direction of the original request — which I think actually strengthens the case for making this configurable.

The current cap (min(16, cpu_cores - 2)) ties workflow concurrency to local CPU, but for many of us the real bottleneck isn't CPU — it's the account rate limit. I have a high core count, so the cap resolves near the 16 ceiling, but I'm on a Claude Max subscription whose rate limit can't sustain that many concurrent agents. The result is a self-inflicted 429 "server is temporarily limiting requests" storm: a large parallel() fan-out has a big chunk of agents fail at the very first model call, and — because an API-error string is still a returned string — the run reports completed with those agents counted as done (see #64177), burning tokens for no usable output.

So the cap is coupled to the wrong resource. cpu_cores - 2 is a reasonable local safeguard, but a workflow's sustainable concurrency is really min(local CPU, what my plan's rate limit allows), and only the user knows the second term.

Concretely, I'd like to be able to set it lower than the CPU-derived default, e.g.:

• ~/.claude/settings.json → "workflow": { "maxConcurrentAgents": 4 }, or
• the per-call form from the OP: parallel(tasks, { maxConcurrency: 4 })

Today the only workaround is to manually chunk parallel() into small batches (e.g. 4–6) with backoff/retry inside the script. It works, but it's boilerplate every workflow author has to reinvent, and nothing about the documented cap hints that you'd need to. A single maxConcurrentAgents knob — clamped to the CPU-derived value as the upper bound — would cover both this issue's "raise it" case and my "lower it to fit my rate limit" case.

Related symptoms of running above the sustainable concurrency: #60562, #64328, #64177.

The min(16, cpu_cores - 2) limit is the right default for single-machine safety, but it becomes a bottleneck fast once you're running workflows designed around parallel verification panels or exhaustive review sweeps — exactly the use cases you listed.

The config-file approach (Option 1) is the better surface for this. A per-workflow override is useful but risks per-script sprawl; a global cap in .claude/settings.json that can be overridden at the workflow level is cleaner. One thing worth adding to the feature request: the limit probably shouldn't just be a raw count — a maxConcurrentAgents plus a maxTotalConcurrentTokens budget guard would prevent the scenario where you raise the ceiling and immediately burn $100 before the first batch completes.

Related: the dedup issue (#64080) and this limit are related failure modes. If the model degenerates and re-emits the same dispatch batch 4×, a higher concurrency limit just multiplies the damage. Both fixes are needed together.

Claudeverse (claudeverse.ai) is approaching this from the coordination-layer angle — tracking fan-out budget as a first-class concept so the orchestrator can say "launch up to N agents, cap total concurrent tokens at X" independently of what the harness enforces. Happy to share notes if useful while this works through the backlog.

{ "workflow": { "maxConcurrentAgents": 32 } }

This great idea, because just now, a single small prompt triggered a deep research run involving 100 agents and consumed 23 million tokens.

When do we have this limit? claude code creates unlimited subagents, ... 56/57 agents done · 1 failed ·.