Codex Max Concurrent Subagents Config: Set a Limit
Prepared and checked using AI. Sources are linked in the article.
To set the Codex max concurrent subagents config, add max_concurrent_threads_per_session under [agents] in config.toml. A value of 2 caps concurrently open spawned-agent threads at two, excluding the primary thread. The cap applies to one Codex session; it is not a machine-wide limit across separate sessions.
[agents]
max_concurrent_threads_per_session = 2
Put the cap in the right config file
Personal defaults belong in ~/.codex/config.toml, while a trusted project can override them with .codex/config.toml. Choose the personal file if you want the same limit across projects. Choose the project file if the team wants a limit suited to one repository’s workload. Codex skips project configuration when the project is untrusted, so use the personal file when you need the setting to apply regardless of project trust.
The TOML section header matters. A bare max_concurrent_threads_per_session = 2 at the top of the file is a different key; the documented setting is agents.max_concurrent_threads_per_session. If an [agents] section already exists, add the line there instead of creating another section. For a project-specific example:
# .codex/config.toml
[agents]
max_concurrent_threads_per_session = 2
The configuration schema requires an integer of at least 1. Pick 1 when you want at most one spawned thread open beside the primary thread. Pick 2 when two independent delegated tasks are useful. Leaving the key unset lets the selected multi-agent backend choose its default, so do not depend on an assumed default number when the limit matters.
agents.max_threads is a legacy alias for agents.max_concurrent_threads_per_session. An existing configuration using the alias can continue to use it, but use the longer key in new examples and avoid setting both names in the same file. That leaves one clear value to review.
Override the limit for one CLI run
Codex accepts -c or --config for a one-off configuration override, using dot notation for nested keys. For example, to start an interactive session with a limit of two:
codex --config agents.max_concurrent_threads_per_session=2
The value here is a TOML integer, so it needs no quotes. The CLI override has higher precedence than project and personal config. This is useful when a broad repository audit calls for a different cap from your usual work, or when you want to try a smaller limit before changing a shared project file. It changes that invocation’s configuration; it does not edit config.toml.
For a persistent choice, edit the appropriate config file. For a single task, pass the override when you start Codex. If an override appears ineffective, check for a higher-precedence CLI value first, then check whether the project config is loaded as a trusted layer. A limit in your personal file can be superseded by a project setting, and a CLI override can supersede both.
Understand what the number limits
The key counts spawned-agent threads that are open concurrently in one session. It excludes the primary thread. Thus 2 means the primary Codex thread plus up to two open spawned threads within that session. It does not mean two total agents, and it does not set a limit shared by every Codex session you start.
The word open also matters. The setting is a thread cap, rather than a target telling Codex to spawn exactly that many agents. A prompt asking for three investigations does not make three slots available when the config allows two. Conversely, setting the cap to three does not require Codex to delegate any work. Current local Codex releases can delegate after a direct request or when applicable project or skill instructions request it.
When you need a predictable shape for a task, combine the config with a specific prompt. For example:
Investigate the parser and the failing tests as two independent tasks. Use no more than two subagents, wait for their findings, then propose one fix.
The prompt describes useful work and the desired handoff; the configuration sets the session ceiling. Give each subagent a bounded responsibility, especially when it might edit files. OpenAI’s subagent guidance recommends starting with read-heavy work such as exploration, tests, triage, and summarization, and taking more care with parallel writes because they can create conflicts and coordination work. For task design beyond the numeric cap, see how to split work for parallel agents.
Choose a cap for the work
Start from the number of genuinely independent tasks, not the number of bullet points in a request. A narrow bug fix with one ordered path may need no delegation. A task with separate code search and test analysis can fit a cap of two. A review divided into correctness, security, and test coverage may justify three if those investigations can proceed independently.
Each subagent performs its own model and tool work, so subagent workflows consume more tokens than comparable single-agent work. A higher cap can allow more work to happen at once, but it also permits more concurrent model and tool activity. Lower the cap when the tasks share mutable files or resources, or when the primary thread would spend more effort coordinating than the parallel work saves. The cap is a ceiling for scheduling, not a quality setting.
If multiple agents need to edit the same repository, decide who owns each area before delegating. A numerical cap does not isolate working directories. For separate Codex sessions doing independent changes, worktrees are a separate way to organize parallel Codex work; the subagent setting still applies per session.
Inspect and manage an active session
In an interactive Codex CLI session, /agent lets you switch between agent threads and inspect their work. You can ask Codex to steer a running subagent, stop it, or close completed subagent threads. These controls help when a task changes after delegation: stop work that is no longer useful, then give the primary thread a narrower instruction.
If you want to disable multi-agent tools, set enabled = false under [agents]. agents.enabled defaults to true, but an enabled features.multi_agent_v2 setting takes precedence over it. Check that feature setting before relying on agents.enabled = false to prevent delegation; setting the cap to 0 is not the documented way to disable the tools.
[agents]
enabled = false
Do not confuse the local Codex setting with the max_concurrent_subagents parameter in OpenAI’s Responses API multi-agent requests. That API parameter belongs in an API request; it is not the key to put in a local Codex config.toml. If you are configuring Codex CLI or its shared local config layers, use [agents] max_concurrent_threads_per_session.
Frequently asked questions
Does a limit of two include the main Codex agent?
No. max_concurrent_threads_per_session = 2 allows up to two open spawned-agent threads alongside the primary thread in that session. The primary thread is excluded from the configured count.
Can I set the limit to zero to turn subagents off?
No. The configuration schema accepts integers starting at 1. Set enabled = false under [agents] to disable multi-agent tools, but check features.multi_agent_v2: when enabled, it takes precedence over agents.enabled, so enabled = false alone will not disable them.
What if my config already uses max_threads?
agents.max_threads is the legacy alias, so existing configurations can keep it. For a new configuration, use agents.max_concurrent_threads_per_session and keep only one spelling in the file.
Does one cap cover several Codex sessions?
No. The setting is explicitly per session, so separate sessions each have their own cap. If you run several sessions in parallel, plan their combined activity separately; lowering one session’s limit does not set a machine-wide ceiling.