Agent concurrency
Uclusion recommends 16 concurrent helpers for Claude Code and Codex. The Codex study below informed this ballpark choice; the same number is used for Claude by design, without a separate Claude capacity benchmark. It is a practical allowance, not a universal safety ceiling for every machine or workload.
Claude Code
The installer adds this to the env object in Claude’s settings:
{
"env": {
"CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS": "16"
}
}
A global install uses ~/.claude/settings.json (or
$CLAUDE_CONFIG_DIR/settings.json); a project install uses
.claude/settings.local.json. Other settings are retained. A project install
also checks inherited user and shared project settings. Both scopes check the
shell environment when no file defines the limit. Overriding an explicit limit
requires your affirmative answer.
Start a new Claude session after updating to ensure the setting is loaded.
Claude’s environment-variable reference
and subagent documentation
confirm this setting for concurrent Agent subagents in Claude Code 2.1.217 and
later; it was also verified in the installed 2.1.319 binary. It accepts a
positive whole number in plain digits. Ultracode sessions are exempt; resumed
agents and user-started /subtask forks can exceed the cap. Workflows and agent
teams follow separate limits.
Codex
When no user-level limit exists, the installer adds this to
~/.codex/config.toml (or the configuration under your CODEX_HOME):
[agents]
max_concurrent_threads_per_session = 16
Existing explicit limits are preserved unless you affirmatively accept the
installer’s override prompt. The legacy agents.max_threads alias is preserved.
An enabled features.multi_agent_v2.max_concurrent_threads_per_session override
counts the coordinator too, so the corresponding value is 17; disabled V2 stays
disabled. This counting was verified with Codex 0.170.0. Restart Codex after an
accepted change. Project installs also configure this user-level limit.
Why 16 helpers
The November 20, 2026 capacity study for B-all-741 compared 4, 8, and 16
helpers, each with one coordinator. It used Codex CLI 0.170.0 with
gpt-6.2-sol at low reasoning effort on a Ryzen AI 7 350 laptop with 8 physical
cores, 16 logical CPUs, and 14.74 GiB RAM. The laptop was also in normal human
use during the runs.
Each case completed the same 16 independent source-inspection and light-test packets: two replicas of eight packets, producing 16 reports and 472 passing tests. Time below runs from root input to the last packet report and excludes the final root summary. Memory is the peak proportional set size (PSS) of the private client, MCP, and tool processes.
| Helpers | Time to 16 reports | Peak private memory | Peak active helpers |
|---|---|---|---|
| 4 | 111.20 seconds | 0.724 GiB | 4 |
| 8 | 79.75 seconds | 0.991 GiB | 8 |
| 16 | 71.96 seconds | 1.198 GiB | 15 |
No out-of-memory event or CPU/memory pressure was observed. Settled helper MCPs had one thread, zero sockets, about 37–38 MiB PSS each, and no accumulated CPU ticks over the final approximately 9.5-second sample. Only the coordinator retained Poke delivery ownership. These are idle observations; serving a request still uses resources.
The 16-helper case retained every report and passing test receipt but lost its final root consolidation/history capture. All 16 helpers started; only 15 overlapped briefly. Later cases used a larger trace allowance and less repeated history capture. There was one run per level, at most four local test packets overlapped, and host I/O also included other laptop activity. This supports headroom for the measured light workload, not a limit for simultaneous heavy builds, browsers, or competing edits. Model usage and provider quotas remain separate constraints.
The human selected 16 as a reasonably large allowance with the observed headroom. The full study preserves the method, actual run order, limitations, and reproduction details; the adjacent results snapshot retains the measurements, packet identities, evidence hashes, and cleanup receipts.