Codex Subagents: Running Agents in Parallel

Who this is for and what you will get

If you want Codex to explore a codebase, run tests and read logs at the same time without filling your main session with that output, this guide is for you. You will learn how to start subagents, write a useful delegation prompt, choose models, watch and steer running agents, and define your own agents.^[1]

What a subagent is

A subagent is an agent that Codex starts for one specific task. A subagent workflow runs several of them in parallel and combines what they return into one response. Each subagent works in its own thread, which you can open to follow its progress in clients that support it.^[1] Current Codex releases turn this on by default. Subagent activity appears in the desktop app, the CLI and the IDE extension.^[1]

Why split the work

Long chats get harder to use. Exploration notes, test logs, stack traces and command output can bury the requirements and decisions that matter. The docs call this context pollution. Output quality can also decline as a chat fills with less relevant detail, which the docs call context rot.^[1]

Subagents move that noise out of the main thread. The main agent keeps the requirements, decisions and final outputs, while subagents run exploration, tests or log analysis in parallel and return summaries instead of raw output.^[1]

There is a cost. Every subagent makes its own model and tool calls, so a workflow uses more tokens than a single-agent run of the same job.^[1] Parallel work fits read-heavy jobs such as exploration, test runs, triage and summarizing. Write-heavy work needs more care, because agents editing the same code at once can collide and add coordination work.^[1]

Starting a subagent workflow

In the CLI, the IDE or the app, ask Codex for subagents directly in the chat. Codex can also delegate when applicable AGENTS.md or skill instructions request it.^[1] In the CLI, /subagents lets you switch between agent threads and inspect one while it runs. The main thread gathers the subagent results into its final response.^[1]

Writing a good delegation prompt

A good prompt does three things. It says how to divide the work, whether Codex should wait for every agent before it continues, and what summary or output each agent should return.^[1] The docs offer this prompt for a pull request review, with one agent per review point:

I would like to review the following points on the current PR (this branch vs main). Spawn one agent per point, wait for all of them, and summarize the result for each point.
1. Security issue
2. Code quality
3. Bugs
4. Race
5. Test flakiness
6. Maintainability of the code

When many agents are running, Codex waits until every requested result is available and then returns one consolidated response.^[1]

Choosing models and reasoning effort

A subagent that has no model or reasoning setting of its own inherits the parent's.^[1] The docs suggest gpt-6.1-sol for demanding, ambiguous, multi-step work that needs planning, tool use, validation and follow-through. They suggest gpt-6-luna for fast, narrowly scoped agents doing clear, repeatable or high-volume work. Both depend on your account or workspace having access.^[1]

Reasoning effort runs from low up to ultra, and which levels you can use depends on the client and the model. high suits agents that trace complex logic, check assumptions or handle edge cases, such as reviewer or security agents. low suits straightforward tasks where speed matters most. Higher effort means slower responses and more tokens, though it can improve results on hard problems.^[1]

Watching and steering running agents

In the desktop app, open a subagent thread from the activity in the main thread to see its work. In the IDE, expand the background-agent panel above the input box to check status, stop active subagents or open a thread.^[1] In the CLI, the app and the IDE alike, you can ask Codex to steer a running subagent, stop it, or close finished agent threads.^[1]

Approvals and sandbox

Subagents inherit the sandbox policy and approval settings of the parent turn. In the CLI that includes changes made with /permissions or --yolo, and a custom agent file cannot replace those settings.^[1]

In interactive CLI sessions, approval requests can come from agent threads you are not looking at. The approval overlay shows the requesting thread, and pressing o opens that thread so you can approve, reject or answer. In non-interactive runs, or whenever a fresh approval cannot be surfaced, an action that needs one fails, and the error goes back to the parent workflow.^[1]

Built-in and custom agents

Codex ships with three built-in agents: default, a general-purpose fallback; worker, for implementation and fixes; and explorer, for read-heavy codebase exploration.^[1]

To define your own, write a standalone TOML file. Personal agents go in ~/.codex/agents/, and project agents go in .codex/agents/. Each file must define name, description and developer_instructions.^[1] A read-only explorer can look like this:

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.
Prefer fast search and targeted file reads over broad scans.
"""

Custom agents inherit the parent's permissions, provider and MCP servers, and their files cannot override those settings. Configure MCP servers in the parent session so the agents can use them.^[1] To narrow what an agent can do, set feature keys such as features.shell_tool or features.apps to false, and turn off individual skills with skills.config.^[1]

Global settings

The [agents] table holds the global settings. agents.enabled defaults to true. agents.max_concurrent_threads_per_session caps how many spawned-agent threads can be open at once, not counting the main thread. agents.default_subagent_model and agents.default_subagent_reasoning_effort set defaults for spawned agents. agents.interrupt_message defaults to true and records a model-visible message when an agent turn is interrupted.^[1]

To cap concurrency at eight threads in a project, set the value in .codex/config.toml:

[agents]
max_concurrent_threads_per_session = 8

One example: a PR review team

A review setup can split the work across three custom agents. pr_explorer maps the codebase and gathers evidence, reviewer looks for correctness, security and test risks, and docs_researcher checks framework or API documentation through a dedicated MCP server.^[1]

Common problems

• Token use climbs quickly. Each subagent does its own work, so reserve parallel runs for tasks that really split into independent pieces.^[1]
• Parallel edits collide. Use parallel agents for reading and checking, and be careful when several agents change code at once.^[1]
• An approval seems stuck. In the CLI, look for the requesting thread label on the approval overlay and press o to open it.^[1]
• A non-interactive run fails on a new approval. Approvals cannot be surfaced in that mode, so set the permissions on the parent session before the run.^[1]

Next steps

The official documentation covers the accepted values for these settings and details on each model.^[1]