# Codex Stops at 4 Subagents. Raise multi_agent_v2 Concurrency

> Codex defaults to 4 concurrent subagents. This multi_agent_v2 config raises the session cap so you can run dozens in parallel. Start small to avoid 429s.

- Author: Kai Wang (AI Kai)
- Published: 2026-09-15
- Updated: 2026-09-15
- Topic: Codex
- Tags: codex, multi-agent, subagents, codex-config, multi-agent-v2
- Canonical: https://hqman.me/blog/codex-multi-agent-v2-parallel-subagents/

Codex stops at 4 subagents on the default `multi_agent_v2` cap. I raise that cap in `~/.codex/config.toml` so Codex can delegate dozens of subagents in parallel.

```toml
[features]
multi_agent_v2 = { enabled = true, max_concurrent_threads_per_session = 40 }
```

If you already have a `[features]` section, add or update the entry there. Then start a new task.

## The 15-agent check

I asked Codex to spawn 15 agents at once, each saying "Hello World". The model in the clip is GPT-6 Astra on Light.

<video controls preload="metadata" poster="/media/blog/codex-multi-agent-v2-parallel-subagents/codex-multi-agent-v2-demo-poster.jpg" width="100%">
  <source src="/media/blog/codex-multi-agent-v2-parallel-subagents/codex-multi-agent-v2-demo.mp4" type="video/mp4" />
  <a href="/media/blog/codex-multi-agent-v2-parallel-subagents/codex-multi-agent-v2-demo.mp4">Download the Codex 15-agent demo</a>
</video>

[Watch the same clip on X](https://x.com/hqmank/status/2099110541234958797)

The sidebar listed Agent 6 through Agent 15 as Working. All 15 stayed open past the default cap.

## The v2 cap, not max_threads

OpenAI's [subagents docs](https://learn.chatgpt.com/docs/agent-configuration/subagents) still document `agents.max_concurrent_threads_per_session` under `[agents]`. They say Codex chooses a default when that field is unset.

My `config.toml` still had `[agents] max_threads = 8`. That line did not keep this run at 8. The `features.multi_agent_v2` cap did.

Use the `[features]` block above if your Codex build already understands `multi_agent_v2`. Then spawn a small set of agents and confirm they all stay open before you raise the number.

## Limits

I hit API 429 errors when I pushed concurrency too high. Start small and increase as needed. A cap of 40 does not add API capacity. It only lets Codex keep more threads open.

Parallel work burns quota faster. One reply on the original post said setting 40 with Astra ate a weekly sub in minutes. I did not measure usage in this Hello World demo. OpenAI later said subagents could pick stronger models than you asked for, which wasted quota until they patched it. I covered that in the [August 30 Codex usage reset notes](https://hqman.me/blog/codex-usage-reset-token-optimization/).

## Sources

- [Original post and 15-agent demo on X](https://x.com/hqmank/status/2099110541234958797)
- [OpenAI Codex subagents](https://learn.chatgpt.com/docs/agent-configuration/subagents)
- [Codex configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference)
- [Codex usage reset and token optimization](https://hqman.me/blog/codex-usage-reset-token-optimization/)