Repository navigation
TUI freeze during agent fan-out #16688
Description
What version of Codex CLI is running?
codex-cli 0.118.0
What subscription do you have?
Codex Pro
Which model were you using?
gpt-5.4
What platform is your computer?
Microsoft Windows NT 10.0.22631.0 x64
What terminal emulator and version are you using (if applicable)?
Windows Terminal (Command Prompt)
What issue are you seeing?
When spawning a large number of sub-agents (e.g. 100), the TUI becomes completely unresponsive.
What steps can reproduce the bug?
- Start the Codex TUI.
- Have the model (or a skill) issue many spawn_agent tool calls in a single turn (e.g. 100 noop agents).
- The TUI freezes
What is the expected behavior?
The TUI should remain responsive and codex should not freeze indefinitely.
Additional information
I've already fixed this issue locally, but like for the other issue I opened I noticed that PRs require approval before being opened.
I wanted to attach videos directly, but for whatever reason GitHub is not allowing me: https://streamable.com/63gerb
Activity
github-actions commentedon Apr 3, 2026
Potential duplicates detected. Please review them and close your issue if it is a duplicate.
Powered by Codex Action
etraut-openai commentedon Apr 3, 2026
Do you have reason to believe this is a recent regression? If you downgrade to 0.116.0, for example, are you able to repro the problem still? I ask because this affects prioritization.
Auties00 commentedon Apr 4, 2026
Happens in that version as well, not sure if it ever worked corretly. If it never did, Let me know if I can open a PR with the fix that works for me locally so maybe we can discuss there what's the best solution.
etraut-openai commentedon Apr 4, 2026
You mentioned that you've "already fixed the issue locally". I presume that you've analyzed the problem and understand the root cause. Can you explain what you've found?
Starting 100 subagents is outside the bounds of the current design. By default, we limit the max number to 6. You've presumably overridden that default value of
agents.max_threadsin your config file. If you start significantly more than 6 subagents, you'll likely hit 429's on the responses API because you'll trigger DDoS detection, so even if the client didn't hang here, you probably wouldn't be able to get this to work. If there's a straightforward fix to prevent hangs, we will entertain it, but I think we'd consider this a low priority.Auties00 commentedon Apr 8, 2026
Actually the API doesn't throw a 429, it could be because my test agents don't do that much work.
Also keep in mind i could reproduce the issue even with 10 agents (I'm running an i7 9700K and 16GBs of DDR4 3200 RAM which seems reasonable for such a workload).
As for the issues I found:
Blocking thread_read RPC in the TUI event loop
hydrate_collab_agent_metadata_for_notification was making a synchronous thread_read RPC to the embedded app-server for every agent notification. When the app-server was busy handling 100 concurrent spawn requests, that RPC queued behind all the spawn work and blocked the TUI event loop. While this was happening, crossterm kept queueing tick events, so after the block finally resolved, each queued tick triggered an expensive render (4+ seconds each), compounding the freeze.
SQLite connection pool contention
Each agent was calling StateRuntime::init(), which opens 2 new SQLite connection pools (state + logs, max_connections(5) each), all pointing at the same DB files, runs migrations (write lock) and attempts VACUUM (exclusive lock).
With 100 agents: 200 pools, up to 1,000 connection attempts, all fighting for SQLite's file-level locks. Process inspection showed 483 threads, mostly blocked on SQLite.
node --version subprocess per agent
Not that important, but i still fixed it: Codex::spawn_internal calls resolve_compatible_node() up to twice per agent (once for JsRepl, once for CodeMode) and each call spawns node.exe as a subprocess to run node --version.
spawn_agent serialized through a write lock
spawn_agent had supports_parallel_tool_calls = false, which in ToolCallRuntime::parallel forced every spawn call to acquire an exclusive RwLock write guard. With 100 spawn tool calls from a single turn, they executed one at a time, each waiting for the previous to complete session init. This doesn't seem to cause any regressions from the automated tests or my own testing, but maybe there was a reason why supports_parallel_tool_calls was set to false.
4 remaining items
92645417d9e5c763259dbebc306e3e commentedon Apr 18, 2026
I can reproduce this on 0.121 on Linux.
In a clean session, I opened sub-agents one by one without forking the main-session context, closed each immediately, and paused 5 seconds between iterations. Around 20 agents, /agent + Tab already took ~5s to show the menu; around 50 agents, ~10s.
In a real session, once it goes past ~20, even waiting 10 minutes does not recover it.
panoanx commentedon Apr 19, 2026
I can reproduce this in my local machine. Codex stuck forever when spawning even like 4+ agents and i have to manually kill the whole window (Ctrl+C, Ctrl+Z do not work either). Btw I'm on a NFS machine (high latency on read/writes) . I'm not sure if it's related.
--
update: after mentioning these, i tried moving the whole ~/.codex to a local ssd mount point. it works way much better. Spawning is fast but navigating through
/agentstill sometimes stucks.djdomi commentedon May 5, 2026
Hi,
since i bought exact for one month Pro, i got this updates for you:
For the 128 update:
logs_2.sqliteto read only, fixed a lot of problems with TUI crashes, i dont know what exactly it prevents, but it stops growing infinite and the tui lasted for me longer (as said, i do not recommended it, but i also using the "YOLO" mode on Codex....)So it seems still, there is a problem, the only thing i did not tried to say codex, to wait x seconds after each spawn, if it will help or crash directly
For the dev:
Uploaded thread: 019d4a69-9705-76f3-9d72-0d417bb7f17d
Auties00 commentedon May 5, 2026
are you running on windows or linux? It could be a windows only issue.
also I don't think I ever said I was sending a /agents command, all I did was run a skill that spawned the agents and the TUI would freeze.
i've listed the issues i've found in my second message, if you are asking which one I think is reponsible for the TUI freeze than it's the first one I've listed, the others are performance issues, but they are not strictly required to fix the TUI freezing.
Here is my fork, in which the TUI doesn't freeze: https://github.com/Auties00/codex
djdomi commentedon May 5, 2026
hey I told my codex to take a sleep 0.5 between the spawns and to let me work with 12 agents,maybe a try worth
Auties00 commentedon May 5, 2026
Do you mind compiling my branch and trying it out? Just to see if it fixes your issue as well (if you ask codex it should be able to compile it for you quiite easily)
Avoid blocking TUI on agent metadata hydration (#21870)
92645417d9e5c763259dbebc306e3e commentedon May 11, 2026
I found the regression. PR #21870 stopped doing synchronous
thread/readmetadata hydration on the TUI render path, which was the right performance direction because large fan-outs could block the UI. The side effect is that collab rows can now render before the TUI haslearned each child agent’s nickname/role, so wait/follow-up rows fall back to raw thread UUIDs even though
/agentlater has the proper names.Avoid blocking TUI on agent metadata hydration (openai#21870)
Avoid blocking TUI on agent metadata hydration (openai#21870)