[FEATURE] Add `maxParallelAgents` Configuration Setting

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Claude Code can spawn an unlimited number of parallel subagent processes, which can overwhelm resource-constrained systems (VPS, small servers) and cause complete system lockups requiring hard reboots.

On December 27, 2025, my server became completely unresponsive while using Claude Code. Investigation revealed that 24 parallel subagent processes were spawned within a 2-minute window, overwhelming the system's disk I/O.

System Specifications

Platform: Linode VPS
OS: Ubuntu (Linux 6.14.3-x86_64-linode168)
CPU: AMD EPYC 7642 48-Core Processor (2 vCPUs allocated)
RAM: 4GB
Swap: 4GB
Disk: 80GB SSD
Claude Code Version: 2.0.76
Model: claude-opus-4-5-20251101

Evidence of Parallel Agent Spawning

The following agent session files were all created/modified within the same 2-minute window (00:19-00:21):

-rw------- 1 root root 1786 Dec 27 00:19 agent-a961218.jsonl
-rw------- 1 root root 1956 Dec 27 00:19 agent-a3d5a00.jsonl
-rw------- 1 root root 2137 Dec 27 00:19 agent-ac1eb27.jsonl
-rw------- 1 root root 2318 Dec 27 00:19 agent-a27b0e8.jsonl
-rw------- 1 root root 2761 Dec 27 00:19 agent-a6d2e1a.jsonl
-rw------- 1 root root 1851 Dec 27 00:20 agent-aa5a497.jsonl
-rw------- 1 root root 1877 Dec 27 00:20 agent-a64b594.jsonl
-rw------- 1 root root 1881 Dec 27 00:20 agent-a2773a9.jsonl
-rw------- 1 root root 1910 Dec 27 00:20 agent-a23376a.jsonl
-rw------- 1 root root 1913 Dec 27 00:20 agent-a361ad1.jsonl
-rw------- 1 root root 1916 Dec 27 00:20 agent-a78ed9a.jsonl
-rw------- 1 root root 1945 Dec 27 00:20 agent-a2dab9c.jsonl
-rw------- 1 root root 3021 Dec 27 00:20 agent-a8aaf7d.jsonl
-rw------- 1 root root 3396 Dec 27 00:20 agent-a7c851c.jsonl
-rw------- 1 root root 3493 Dec 27 00:20 agent-a9f250b.jsonl
-rw------- 1 root root 3633 Dec 27 00:20 agent-afedd05.jsonl
-rw------- 1 root root 3961 Dec 27 00:20 agent-a8a897a.jsonl
-rw------- 1 root root 5384 Dec 27 00:20 agent-a09c5fe.jsonl
-rw------- 1 root root 1744 Dec 27 00:21 agent-a5ffb9b.jsonl
-rw------- 1 root root 1929 Dec 27 00:21 agent-ab9015c.jsonl
-rw------- 1 root root 1969 Dec 27 00:21 agent-ace58e4.jsonl
-rw------- 1 root root 2113 Dec 27 00:21 agent-a7eca68.jsonl
-rw------- 1 root root 3388 Dec 27 00:21 agent-a072cd8.jsonl
-rw------- 1 root root 4296 Dec 27 00:21 agent-a7ccb53.jsonl

System Impact

Linode monitoring captured the moment of lockup:

| Metric | Normal Average | At Lockup (12:20 AM) | Multiple |
|--------|----------------|----------------------|----------|
| CPU % | 7.59% | 42.77% | 5.6x |
| Disk I/O (blocks/s) | 8.83 | 152.80 | 17.3x |

The 17x disk I/O spike caused complete system unresponsiveness. No OOM killer activity was logged—the system locked up due to I/O saturation before memory limits were reached. A hard reboot was required.

Documentation Contradiction

The Claude Code documentation states:

"Subagents operate sequentially, not in parallel."

However, the evidence above shows either parallel execution — 24 agent files with overlapping timestamps within a 2-minute window — or, it's spawning so quickly that they're happening sequentially but as fast as the system can spawn them. This occurs when Claude issues multiple Task tool calls in a single response. _(The documentation is a little vague -- does "sequentially" in this instance mean that the agents are spawning one at a time -- completing its task before spawning another -- or, does it just mean that you're spawning all of the agents one after another as fast as you can?)_

Proposed Solution

Add a new configuration setting to ~/.claude/settings.json:

{
  "maxParallelAgents": 3
}

Suggested Behavior

| Setting | Value | Description |
|---------|-------|-------------|
| Default | 5 | Reasonable for most systems |
| Minimum | 1 | Forces sequential execution |
| Maximum | unlimited or -1 | Current behavior |

When the limit is reached, queue additional agent requests and execute them as running agents complete.

CLI Integration

claude config set maxParallelAgents 3
claude config get maxParallelAgents

Alternative Solutions

1. maxAgentMemoryMB: Limit total memory allocated to all agents combined
2. agentSpawnDelayMs: Add a minimum delay (in milliseconds) between spawning agents
3. Auto-detection: Detect available system resources (CPU cores, free memory) and auto-limit accordingly
4. Per-session limit: Allow setting limits per session via CLI flag: claude --max-agents 3

Priority

High - Significant impact on productivity

Feature Category

Configuration and settings

Use Case Example

A developer running Claude Code on a 4GB VPS asks Claude to analyze Apache access logs for suspicious patterns. Claude decides to spawn multiple parallel agents to:

• Search for specific log patterns
• Read configuration files
• Check multiple log files simultaneously
• Cross-reference IP addresses

Without limits, 20+ agents spawn simultaneously. Each agent:

• Consumes memory (Node.js process overhead)
• Writes to its own session file on disk
• Competes for disk I/O bandwidth

On a small VPS with limited I/O bandwidth, this causes an I/O storm that makes the system completely unresponsive.

With maxParallelAgents: 3, the same task completes successfully (albeit slightly slower) without risking system stability.

Additional Context

Current Workaround

Until this feature is implemented, I've had to implement OS-level protections that affect all processes, not just Claude Code:

# /etc/security/limits.conf
root            soft    nproc           100
root            hard    nproc           150

This will hopefully cause the kernel to kill runaway processes rather than allowing system lockup, but it's a blunt instrument.

Impact

This issue makes Claude Code risky to use on small VPS instances for any task that might trigger parallel agent execution. Users have no way to prevent or limit this behavior, and the only recovery from a lockup is a hard reboot.