[Feature Request] Add configurable concurrency limiter for parallel agents with lower default

Agreed. There are multiple other issues requesting a "max parallel agents" config setting where the issues are closed and no response from anybody at Anthropic. I just had a server go down this morning because of wild system resource usage from parallel agents.

It's possible that a simple instruction to the primary agent "Spawn no more than n parallel sub-agents" would control it, but I have not tested this. Maybe put in global CLAUDE.md file.

e-volusian is right that a CLAUDE.md instruction works, and I can confirm it. We use it in our multi-agent polling runner to prevent exactly this "bomb" scenario.

The two things that have worked best in practice:

1. CLAUDE.md global constraint

# Concurrency limits
Spawn no more than 5 concurrent subagents at one time. If a task would benefit from more parallelism, batch it into waves of 5 and process each wave sequentially before spawning the next.

This is not enforced at the platform level, but compliance is surprisingly reliable - the model reads CLAUDE.md at session start and applies the constraint consistently. The key is stating a specific number rather than "a reasonable number."

2. PreToolUse hook as a hard gate

For situations where you cannot trust the model to self-limit (e.g. recursive spawning, skills that themselves spawn agents), a hook is more reliable:

#!/bin/bash
# ~/.claude/hooks/subagent-limit.sh
# Block Agent tool calls when active count >= MAX
MAX=${CC_MAX_SUBAGENTS:-5}
COUNTER_DIR="${HOME}/.claude/agent-counter"
mkdir -p "$COUNTER_DIR"
# Count files younger than 30 minutes (heuristic for "still running")
ACTIVE=$(find "$COUNTER_DIR" -mmin -30 | wc -l)
if [ "$ACTIVE" -ge "$MAX" ]; then
  echo "Blocked: $ACTIVE subagents active (limit: $MAX)" >&2
  exit 2
fi
touch "$COUNTER_DIR/$(date +%s%N)"

Then in settings.json:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Agent",
      "hooks": [{"type": "command", "command": "bash ~/.claude/hooks/subagent-limit.sh"}]
    }]
  }
}

Both stop the runaway fan-out problem, but neither is a substitute for first-party support (a max_concurrent_agents config value). The hook approach has edge cases - the file-based counter doesn't clean up on crash, which can leave phantom counts. The platform just needs a hard cap.

(I build tooling for orchestrating multiple Claude Code sessions at scale - disclosure: we run into this exact problem and these are workarounds we use ourselves, not a recommendation to not fix the root cause.)

Thanks for reporting this. Since Claude Code v2.1.217 there is a cap on concurrently running subagents (default 20), and you can lower it with the CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS environment variable, e.g. CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=5. Spawning past the cap fails and Claude is told not to retry.

Changelog: https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
Docs: https://code.claude.com/docs/en/sub-agents#concurrent-subagent-limit

Please update to the latest version and let us know if you still see unbounded fan-out.

🤖 Generated with Claude Code