Subagents are on by default in the Codex CLI, the IDE extension and the ChatGPT desktop app, but Codex spawns them only when you ask, or when AGENTS.md or a skill tells it to. A custom agent is a TOML file in .codex/agents/ with a name, a description and developer_instructions.
pr-watch on overnight findings and the onboarding switch
pr-watch collected the review findings on the open pull requests16m
Fixed the findings that held up12m
Waited for CI on the fix push7m
Ask ZestWhich Codex skills end in merged PRs?
01See your team’s AI stack
Winding /Teams Last 30 days
Zest
3 Members 1 Agent
Team overview
67%
AI Adoption▲ 34 pts
240
PRs Merged▲ 101
96.1h
Median AI Time▲ 9.5h
57.2h
Build Hours▲ 20.3h
This week
Member
AI
PRs/wk
AI Task
Plan
Impl
Last Standup
AI Stack
22.8/wk
28 min ago
15.8/wk
12 min ago
4/wk
Aug 14
—
2 hours ago
Current AI models & harnesses As of Sep 8
Claude CodeFable 5.1 (max) (with fallback)70.4 · Coding Agent Index
CodexGPT-6 Astra (max)67.0 · Coding Agent Index
Muse CodeMuse Spark 1.3 (xhigh)64.2 · Coding Agent Index
Grok BuildGrok 4.5 (high)64.1 · Coding Agent Index
Kimi Code CLIKimi K362.6 · Coding Agent Index
OpencodeGemini 3.8 Flash (high)61.2 · Coding Agent Index
Cursor CLIComposer 2.5 Fast38.3 · Coding Agent Index
Demo setups use current model families. The pairings above are the combinations benchmarked by Artificial Analysis; rankings measure performance, not popularity.
Illustrative daily trends · Other totals: last 30 days. Build Hours: this week, model-estimated activity including overlap; not engineer hours.
USED BY ENGINEERING TEAMS AT
Not starting today? What's in the way?
How to use subagents in Codex
Ask for them. Current Codex releases spawn subagents only when your request says so, or when an AGENTS.md or skill instruction does, so phrases like 'spawn two agents' or 'one agent per point' are what start them. OpenAI's own review prompt shows the three things a good request settles: how to split the work, whether to wait for every agent, and what to hand back.
Each subagent works in its own agent thread, and the main thread folds their results into one answer.
A Codex prompt
Review this branch with parallel subagents. Spawn one subagent for
security risks, one for test gaps, and one for maintainability. Wait for
all three, then summarize the findings by category with file references.
How to see and steer running subagents
Every Codex client shows the agent threads, with different controls in each:
CLI: /subagents switches between the agent threads while they run. An approval request can come from a thread you aren't looking at; the overlay names that thread, and o opens it before you answer.
IDE extension: when the background-agent panel is available, active subagents sit above the composer. Expand it to see each one's status, stop them all, or open a single thread.
ChatGPT desktop app: open a subagent's thread from the activity in the main chat. To steer, stop or close one, ask Codex in the main chat.
How to create a custom agent in .codex/agents
Codex comes with three agents: default (a general-purpose fallback), worker (implementation and fixes) and explorer (read-heavy exploration). Your own agent is one TOML file, in .codex/agents/ to share it through the repository or in ~/.codex/agents/ to keep it to yourself.
Three keys are required: name, description and developer_instructions. Codex knows the agent by its name key, not the file name, and a custom agent named explorer takes the built-in's place. This one, adapted from OpenAI's PR-review example, maps code on a fast model and leaves the editing to others:
.codex/agents/pr-explorer.toml
name = "pr_explorer"
description = "Read-only codebase explorer for gathering evidence before changes are proposed."
model = "gpt-6-luna"
model_reasoning_effort = "high"
developer_instructions = """
Stay in exploration mode.
Do not edit files.
Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks for them.
"""
Then, in a Codex prompt
Have pr_explorer map the code paths this branch touches, then summarize them.
Custom agent fields
Beyond the three required keys, a custom agent file can change the model and take capabilities away. Skills come from the parent session, and managed requirements still apply to every agent.
Keys a custom agent file accepts, from OpenAI's subagents docs and configuration reference, read November 11, 2026.
Key
What it does
name
Required. What Codex spawns and refers to the agent by
description
Required. Tells Codex when to use this agent
developer_instructions
Required. The instructions that define its behavior
model, model_reasoning_effort
Its model and effort; these beat every default
model_reasoning_summary, model_verbosity
More model settings, with the values config.toml accepts
No effect here: the agent keeps the parent session's
Codex subagent settings in config.toml
Settings for every subagent go under [agents] in ~/.codex/config.toml or a project's .codex/config.toml. The multi-agent tools behind them, starting with spawn_agent, are on by default. The keys:
enabled: false removes the multi-agent tools.
max_concurrent_threads_per_session: how many spawned threads can be open at once, the main thread not counted. OpenAI's docs don't give a default; in the 0.167.2 source it's 3 spawned threads for GPT-6 models and 6 for older ones. Older configs call it max_threads, which still works.
default_subagent_model and default_subagent_reasoning_effort: for every spawned agent, unless the spawn request names its own.
interrupt_message: on by default, it leaves the agent a message it can see when its turn is interrupted.
For one run, override any of them with -c, as in codex -c agents.enabled=false. Older setups declare roles as [agents.<name>] tables with a description and a config_file, which the configuration reference still lists.
The parent's model and reasoning effort, unless something overrides them. A value written in the custom agent file wins outright. Without one, Codex takes a model or effort named in the spawn request ('use gpt-6-luna for the scans'), then the [agents] defaults, then the parent's.
When a spawn request or an [agents] default picks a model but no effort, the subagent runs at that model's default effort rather than the parent's. And an agent file that sets only model keeps the effort resolved before it, so add model_reasoning_effort when the new model doesn't support that level. OpenAI points to gpt-6.1-sol for agents that plan and check their own work, and gpt-6-luna for fast, narrow ones.
What a subagent inherits: sandbox, approvals and MCP servers
A Codex subagent runs under the parent turn's sandbox and approval settings, including any change made with /permissions or --yolo, and a custom agent file can't swap in its own. It also gets the parent's model provider and MCP servers, so an MCP server an agent needs goes in the parent session's config.
'Do not edit files' in developer_instructions is a request, not a read-only sandbox. Pick the sandbox before you ask Codex to delegate. OpenAI's advice is to start with read-heavy work (exploration, tests, triage, summaries), since agents editing code at the same time can conflict.
In codex exec, or any run that can't show a new approval, a subagent action that needs one fails and the error goes back to the parent. codex exec starts in a read-only sandbox and prints only the final message, which suits a parallel review:
codex exec "Review this branch against main with one subagent each for security, test gaps and maintainability. Wait for all three, then list the findings by category with file references." > review.md
Hooks for Codex subagents
SubagentStart runs when a subagent starts, with its matcher tested against agent_type. Plain text the hook prints is added to that subagent's developer context, a place for rules only one agent needs; continue: false doesn't stop the subagent. SubagentStop runs when it stops, while Interrupt and SessionEnd never run for subagents. Codex skips a new or changed hook until you trust it in /hooks.
A Claude Code subagent can be held to read-only tools by its own file; a Codex subagent works with whatever its parent session allows. Claude Code also delegates without being asked when a task matches a description, which current local Codex releases don't.
To move agents across, type /import in an idle Codex CLI session and pick Claude Code. It converts Claude Code subagents into Codex ones, and OpenAI asks you to review the tool restrictions and permissions it carried over. The Claude Code side, with agent teams, is on Claude Code subagents.
From OpenAI's subagents and import docs and Anthropic's subagents doc, read November 11, 2026.
Codex
Claude Code
Definition
TOML in .codex/agents/ or ~/.codex/agents/
Markdown with YAML frontmatter in .claude/agents/ or ~/.claude/agents/
Required
name, description, developer_instructions
name, description; the body is the system prompt
When it delegates
When you ask, or AGENTS.md or a skill asks
Also on its own, when a task matches a description
Built-in agents
default, worker, explorer
Explore, Plan and general-purpose, among others
Permissions
Always the parent's sandbox and approvals
permissionMode, tools and disallowedTools per subagent
MCP servers
The parent's
Its own, through mcpServers
Other ways to run Codex work in parallel
Subagents split one task inside one session. For separate tasks, Codex documents three other routes:
Worktrees in the ChatGPT desktop app: choose Worktree under the composer, and each chat gets its own Git worktree of the repository, so several run without touching your checkout. Hand off brings a chat back to Local.
Codex Cloud: every task gets a workspace of its own and keeps going while your computer sleeps.
codex agents: the agent command center, listing the chats on a shared local or remote server and switching between them.
How much Codex subagents add: our numbers
Each subagent does its own model and tool work, so OpenAI warns that a subagent run spends more tokens than one agent doing the same job. On one of our engineers' laptops, Codex's subagent threads outnumbered the sessions the engineer started: 188 against 180 between June 21 and September 22, 2026, from 222 spawn_agent calls. Codex keeps each thread as a session of its own.
To see what that leaves of a plan, run /status in the CLI; the five-hour and weekly limits are on Codex usage limits.
What Zest shows about Codex subagents
Nothing yet. Zest's Codex plugin uploads each Codex session's main thread, with its model, tokens, skills and MCP tools, next to the pull requests the engineer merged. It skips the threads subagents run in, so their tokens and tool calls don't reach Zest, and it doesn't list which agents a session spawned; for Claude Code it does list each session's subagents.
Starter is free (3 seats, no credit card). Pro is $49 a month with 5 seats and Max is $149 a month with 10 seats — priced per workspace, not per engineer, with extra seats at $19 a month. See pricing
Yes. Current Codex releases turn subagent workflows on by default in the CLI, the IDE extension and the ChatGPT desktop app. Codex spawns them only when you ask, or when AGENTS.md or a skill tells it to, and ships default, worker and explorer agents.
How many subagents can Codex run at once?+
As many as agents.max_concurrent_threads_per_session in config.toml allows, counting spawned threads and not the main one. With the key unset, the 0.167.2 source allows 3 at a time for GPT-6 models and 6 for older ones; OpenAI's docs don't give the number.
Can a Codex subagent use a different model?+
Yes. Name the model in your request, set default_subagent_model under [agents], or put model and model_reasoning_effort in the custom agent's TOML file, which wins over both. With none of them, a subagent runs on the parent's model and effort.
Can Codex use my Claude Code subagents?+
Codex reads custom agents as TOML from .codex/agents/ and ~/.codex/agents/. To bring Claude Code's over, type /import in an idle Codex CLI session and choose Claude Code, then check the tool restrictions and permissions on what it imported.
How do I turn off subagents in Codex?+
Set enabled = false under [agents] in config.toml, or pass -c agents.enabled=false for a single run. Admins can pin features.multi_agent on or off for managed users in requirements.toml.