A config snippet is going around this week: set agents.max_concurrent_threads_per_session = 64 in your Codex config.toml and watch one session fan out into dozens of subagents. The post that started it claims the default is 3 and that OpenAI tested 64. The setting is real. The two numbers are not in the documentation, and the interesting part is not the cap at all. It is what happens to the work when you raise it.
This post covers what the setting actually does, per the Codex reference, and the three things that fail in order once a single session is running more agents than one person can read.
TL;DR
agents.max_concurrent_threads_per_session caps how many spawned-agent threads Codex keeps open at once, not counting the primary thread. The reference does not publish a default; it says Codex chooses one when the key is unset. Subagents return summaries to the main thread, which waits for all of them and replies once, and the docs recommend them for read-heavy work while warning that parallel write-heavy workflows create conflicts and coordination overhead. Raising the cap to 64 stresses exactly those two points: shared files and a single consolidated reply nobody can audit. Sharkly runs Codex as a Runtime and moves the parallelism up a level, where each run is a Task with its own worktree, its own log, and its own reviewer.
What the setting does
Three keys in the [agents] section of config.toml matter here. The wording below is from the configuration reference.
| Key | What the reference says |
|---|---|
agents.max_concurrent_threads_per_session |
“Maximum number of spawned-agent threads that can be open concurrently, excluding the primary thread. When unset, Codex chooses the default.” |
agents.max_threads |
“Legacy alias for agents.max_concurrent_threads_per_session.” |
agents.enabled |
“Enable or disable multi-agent tools (default: true).” |
Two related keys, agents.default_subagent_model and agents.default_subagent_reasoning_effort, set what spawned agents run on unless a spawn call says otherwise.
So the snippet works as written:
[agents]
max_concurrent_threads_per_session = 64
What the reference does not say is what the default is, or that any value was tested. Treat “default 3” and “OpenAI tested 64” as claims from a post, not from the vendor, until the docs say otherwise.
The subagents guide adds the two sentences that decide whether raising the cap is a good idea. On results: “When many agents are running, Codex waits until all requested results are available, then returns a consolidated response.” On fit: subagents suit “read-heavy tasks such as exploration, tests, triage, and summarization,” and the guide advises caution with “parallel write-heavy workflows, because agents editing code at once can create conflicts and increase coordination overhead.”
Read those together and the failure order writes itself.
What breaks first: the shared checkout
Subagents in one session share the session’s working directory unless you arrange otherwise. That is fine for sixty-four agents reading. It is a merge problem for four agents writing.
The failure is not dramatic. Two subagents edit the same file, the second write wins, and the consolidated summary reports both tasks complete. You find out in review, if you have a review, or in production if you do not. The docs’ warning about conflicts and coordination overhead is describing this.
The fix is the one every parallel-agent setup converges on: one working copy per unit of work. In Sharkly, each Task run gets an isolated directory, and repository-backed work uses a separate git worktree per run, which is the mechanism covered in parallel agents in isolated worktrees. Ten Tasks against one repository, zero shared state. The Runtime doing the editing can still be Codex; the isolation is provided around it.
What breaks second: the consolidated reply
Codex waits for every subagent and returns one response. At four subagents that is a convenience. At sixty-four it is a single message summarizing sixty-four pieces of work, written by the agent that dispatched them, with the intermediate output folded away.
That is the wrong shape for review. A reviewer needs to know what each unit of work touched, what it ran, and where it stopped, and needs to be able to accept or reject each one on its own. A summary of summaries cannot be partially accepted.
Sharkly stores the Agent’s final response on the Task, and keeps an execution log per run with the trigger, start and end, tool calls, Runtime events, and failure details. Executions sit in their own tab, separate from the comment timeline. Sixty-four units of work are sixty-four Tasks with sixty-four logs, each one reviewable, each one returning its result to the place a person will look.
What breaks third: the human in the loop
The cap says nothing about what happens when a subagent needs a person. Inside one session, a blocked subagent is a thread that has gone quiet in a consolidated wait. The main thread cannot answer for you, and you cannot see which of sixty-four threads is the one that stopped.
Sharkly keeps Task status and Agent working state separate: a Started Task can show Working, Waiting for human reply, Waiting for human review, or Error. Waiting and failed signals land in the Primary section of the Inbox for the responsible person, and a reply on the Task starts the follow-up run with the thread as context. The stuck one tells you, instead of hanging inside a wait you cannot inspect.
Subagents or Tasks? A decision pair
Use Codex subagents inside one session when the work is read-heavy and converges on one answer: explore a codebase, triage a batch of failures, summarize a set of documents, run a suite of tests. That is what the guide recommends them for, and a higher cap is cheap when nothing is writing.
Use separate Tasks, each assigned to an Agent on a Computer, when the units of work write code, when different people will review different pieces, or when a person may need to answer mid-run. Sharkly is not a replacement for Codex; Codex is the Runtime that executes each Task. The difference is where the parallelism lives: inside one session’s consolidated wait, or across a board where context, progress, blockers, results, and human review stay visible from request to release.
Raising the cap the safe way
If you do raise max_concurrent_threads_per_session, do it the way Sharkly’s own concurrency docs describe for Computers: increase only after the current setup handles the existing workload reliably, because higher concurrency consumes more CPU, memory, disk, provider capacity, and repository bandwidth. A Computer in Sharkly has its own task concurrency limit, and Agents using temporary directories default to half of it. Capacity is bounded by the Computer, the Agent’s concurrency, and directory availability, and an online Agent can still have queued work when that capacity is full.
Provider capacity is the one people forget. Sixty-four threads against one API key is sixty-four ways to hit a rate limit at once, and a 429 that means “quota exhausted” is not fixed by retrying. Sharkly’s failed-run log keeps the provider’s original response alongside a plain title, so the difference is visible before anyone retries.
Frequently asked questions
What is the default value of agents.max_concurrent_threads_per_session? The configuration reference does not state one. It says Codex chooses the default when the key is unset. Numbers circulating on social media are not from the reference.
Does raising the cap make Codex faster? For read-heavy fan-out, more threads finish sooner. For write-heavy work, the docs warn that concurrent edits create conflicts and coordination overhead, which costs more time than the parallelism saves.
Do Codex subagents run in separate git worktrees? The subagents guide does not say they do. Plan as if they share the working directory unless you have set up isolation yourself.
How does Sharkly use Codex? As a Runtime. A Computer running Codex reports it as available, and Tasks assigned to an Agent on that Computer execute through it, each run in its own isolated directory or worktree.
Can I still use subagents inside a Sharkly Task? Yes. Everything the Runtime can do on its own still works inside the run. Sharkly adds the Task, the isolation, the log, and the review around it.
The short version
The setting is real and the snippet works. What it does not do is make sixty-four concurrent edits safe, make one consolidated reply reviewable, or tell you which thread is waiting on you. Those are the three things that break, in that order. Keep subagents for read-heavy fan-out, and put write-heavy parallel work on a board where each run has its own worktree and its own reviewer. Connect one Computer with Codex on it, create one Agent, and assign it something boring. The docs cover each concept in more depth: docs.sharkly.ai.
