Orchestrator Pattern on Codex
What the orchestrator skill does under the covers on Codex: everything routes through one main thread, subagents can't nest, and a few settings decide how many workers you can keep open.
This is the Codex side of the orchestrator pattern: what the orchestrator skill is doing under the covers when it runs on Codex, and the gotchas to know going in. Everything below was checked against the official docs and codex-cli 0.155.1. Codex's multi-agent features are moving fast, so when your installed CLI disagrees with this page, trust the CLI.
One main thread runs everything
Codex calls this a subagent workflow. The main thread (the docs also call it the "main agent" or "primary thread") hands bounded tasks to subagents, each working in its own agent thread. The main thread collects their results and can steer a running subagent with follow-up instructions. On Codex, the orchestrator is the main thread.
The biggest difference from Claude Code is communication. Codex documents no way for separately started sessions to message each other, and with default settings spawned subagents can't address each other either. So every message goes from a worker to the main thread and back.
Two ways to run the workers
The skill works with either, and the orchestrator picks per initiative:
- Spawned subagents. The main thread spawns one subagent per slice and gets each completion report back automatically. The tradeoff is the per-slice brainstorm with you: a subagent runs from its brief, so the orchestrator settles each slice's spec in the main thread before spawning, and the brief carries everything.
- Separate sessions. You open a Codex session per slice and work it interactively, which keeps the brainstorm and review. With no messaging between sessions, coordination runs through the initiative doc, the Git state, and you relaying reports.
Slices that need real design conversation suit separate sessions. Well-specified slices suit spawned subagents.
Subagents can't nest
In the Codex source, agent nesting depth defaults to 1 (agents.max_depth), so a subagent can't spawn subagents of its own. That key isn't in the published config reference, so it's an implementation detail rather than a setting to tune.
It matters because of how the pattern splits models: a fast model implements, a stronger model reviews. On Claude Code a worker runs both as its own subagents. On Codex the fan-out stays flat instead:
- The worker subagent implements its slice from the spec and reports back.
- The main thread spawns a separate review subagent for that slice, on a stronger model or higher reasoning effort.
- Review findings go back to the worker as a follow-up, or to a fresh worker.
Gotchas for long runs
- Close finished threads.
agents.max_concurrent_threads_per_sessioncaps how many spawned threads can be open at once, and a finished subagent holds its slot until it's closed. The orchestrator closes each one after consolidating its report. - Approvals can stall a wait. An approval request from a background subagent can surface while you're looking at the main thread. If a "wait for all reports" step seems slow, check for an unanswered prompt.
- The web sidebar is read-only. It shows subagent activity but can't stop or steer one. Drive the run from the app, the CLI, or the IDE.
- The slash commands differ from the docs. In codex-cli 0.155.1,
/agentsswitches between all active agent sessions and/subagentsswitches between this session's subagents. OpenAI's docs say/agent, which doesn't exist in the CLI.
Where the model split lives
Codex has built-in roles named default, worker, and explorer, and you can define custom agents in .codex/agents/*.toml (per project) or ~/.codex/agents/*.toml (personal). A custom agent sets name, description, and developer_instructions, and can also set model, model_reasoning_effort, sandbox_mode, MCP servers, and skills. That's where the fast implementer and the stronger reviewer get defined.
Multi-agent defaults live under [agents] in config.toml: agents.enabled (on by default), agents.max_concurrent_threads_per_session (with agents.max_threads as a legacy alias), agents.default_subagent_model, agents.default_subagent_reasoning_effort, and agents.interrupt_message. Explicit spawn settings override these. Run codex features list to see what your install has turned on.
Permissions stay with the session
Subagents inherit the main thread's sandbox and approval settings unless their own config says otherwise. A blocked action comes back to you. Another agent's go-ahead never counts as yours.
The short version
On Codex the orchestrator is the hub: it spawns the workers, runs the reviews, and closes threads as it goes. Settle each slice's spec before spawning so the brief can carry everything the worker needs.
This guide was my gift to you. I want everyone to be able to punch above their weight class by leveraging AI to do more with what they've got.
If this helped and you want to know how I help companies through AI consulting, mentoring, or workshops — sign up for my email list or reach out below.