subagents.md Codex Docs, 2026-03-14 00:32 UTC → 2026-03-17 00:33 UTC

1# Multi-agents1# Subagents

2 2 

3Codex can run multi-agent workflows by spawning specialized agents in parallel and then collecting their results in one response. This can be particularly helpful for complex tasks that are highly parallel, such as codebase exploration or implementing a multi-step feature plan.3Codex can run subagent workflows by spawning specialized agents in parallel and then collecting their results in one response. This can be particularly helpful for complex tasks that are highly parallel, such as codebase exploration or implementing a multi-step feature plan.

4 4 

5With multi-agent workflows you can also define your own set of agents with different model configurations and instructions depending on the agent.5With subagent workflows, you can also define your own custom agents with different model configurations and instructions depending on the task.

6 6 

7For the concepts and tradeoffs behind multi-agent workflows (including context pollution/context rot and model-selection guidance), see [Multi-agents concepts](https://developers.openai.com/codex/concepts/multi-agents).7For the concepts and tradeoffs behind subagent workflows, including context pollution, context rot, and model-selection guidance, see [Subagent concepts](https://developers.openai.com/codex/concepts/subagents).

8 8 

9## Enable multi-agent9## Availability

10 10 

11Multi-agent workflows are currently experimental and need to be explicitly enabled.11Current Codex releases enable subagent workflows by default.

12 12 

13You can enable this feature from the CLI with `/experimental`. Enable13Subagent activity is currently surfaced in the Codex app and CLI. Visibility

14**Multi-agents**, then restart Codex.14 in the IDE Extension is coming soon.

15 15 

16Multi-agent activity is currently surfaced in the CLI. Visibility in other16Codex only spawns subagents when you explicitly ask it to. Because each

17surfaces (the Codex app and IDE Extension) is coming soon.17subagent does its own model and tool work, subagent workflows consume more

18 18tokens than comparable single-agent runs.

19You can also add the [`multi_agent` feature flag](https://developers.openai.com/codex/config-basic#feature-flags) directly to your configuration file (`~/.codex/config.toml`):

20 

21```

22[features]

23multi_agent = true

24```

25 19 

26## Typical workflow20## Typical workflow

27 21 

28Codex handles orchestration across agents, including spawning new sub-agents, routing follow-up instructions, waiting for results, and closing agent threads.22Codex handles orchestration across agents, including spawning new subagents,

29 23routing follow-up instructions, waiting for results, and closing agent

30When many agents are running, Codex waits until all requested results are available, then returns a consolidated response.24threads.

31 25 

32Codex will automatically decide when to spawn a new agent or you can explicitly ask it to do so.26When many agents are running, Codex waits until all requested results are

27available, then returns a consolidated response.

33 28 

34For long-running commands or polling workflows, Codex can also use the built-in `monitor` role, tuned for waiting and repeated status checks.29Codex only spawns a new agent when you explicitly ask it to do so.

35 30 

36To see it in action, try the following prompt on your project:31To see it in action, try the following prompt on your project:

37 32 

38```33```text

39I 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.34I 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.

401. Security issue351. Security issue

412. Code quality362. Code quality

456. Maintainability of the code406. Maintainability of the code

46```41```

47 42 

48## Managing sub-agents43## Managing subagents

49 44 

50- Use `/agent` in the CLI to switch between active agent threads and inspect the ongoing thread.45- Use `/agent` in the CLI to switch between active agent threads and inspect the ongoing thread.

51- Ask Codex directly to steer a running sub-agent, stop it, or close completed agent threads.46- Ask Codex directly to steer a running subagent, stop it, or close completed agent threads.

52- The `wait` tool supports long polling windows for monitoring workflows (up to 1 hour per call).

53 

54## Process CSV batches with sub-agents

55 

56Use `spawn_agents_on_csv` when you have many similar tasks that map to one row per work item. Codex reads the CSV, spawns one worker sub-agent per row, waits for the full batch to finish, and exports the combined results to CSV.

57 

58This works well for repeated audits such as:

59 

60- reviewing one file, package, or service per row

61- checking a list of incidents, PRs, or migration targets

62- generating structured summaries for many similar inputs

63 

64The tool accepts:

65 

66- `csv_path` for the source CSV

67- `instruction` for the worker prompt template, using `{column_name}` placeholders

68- `id_column` when you want stable item ids from a specific column

69- `output_schema` when each worker should return a JSON object with a fixed shape

70- `output_csv_path`, `max_concurrency`, and `max_runtime_seconds` for job control

71 

72Each worker must call `report_agent_job_result` exactly once. If a worker exits without reporting a result, Codex marks that row with an error in the exported CSV.

73 

74Example prompt:

75 

76```

77Create /tmp/components.csv with columns path,owner and one row per frontend component.

78 

79Then call spawn_agents_on_csv with:

80- csv_path: /tmp/components.csv

81- id_column: path

82- instruction: "Review {path} owned by {owner}. Return JSON with keys path, risk, summary, and follow_up via report_agent_job_result."

83- output_csv_path: /tmp/components-review.csv

84- output_schema: an object with required string fields path, risk, summary, and follow_up

85```

86 

87When you run this through `codex exec`, Codex shows a single-line progress update on `stderr` while the batch is running. The exported CSV includes the original row data plus metadata such as `job_id`, `item_id`, `status`, `last_error`, and `result_json`.

88 

89Related runtime settings:

90 

91- `agents.max_threads` caps how many agent threads can stay open concurrently.

92- `agents.job_max_runtime_seconds` sets the default per-worker timeout for CSV fan-out jobs. A per-call `max_runtime_seconds` override takes precedence.

93- `sqlite_home` controls where Codex stores the SQLite-backed state used for agent jobs and their exported results.

94 47 

95## Approvals and sandbox controls48## Approvals and sandbox controls

96 49 

97Sub-agents inherit your current sandbox policy.50Subagents inherit your current sandbox policy.

98 51 

99In interactive CLI sessions, approval requests can surface from inactive agent52In interactive CLI sessions, approval requests can surface from inactive agent

100threads even while you are looking at the main thread. The approval overlay53threads even while you are looking at the main thread. The approval overlay

101shows the source thread label, and you can press `o` to open that thread before54shows the source thread label, and you can press `o` to open that thread before

102you approve, reject, or answer the request.55you approve, reject, or answer the request.

103 56 

104In non-interactive flows, or whenever a run can’t surface a fresh approval,57In non-interactive flows, or whenever a run can't surface a fresh approval, an

105an action that needs new approval fails and Codex surfaces the error back to the58action that needs new approval fails and Codex surfaces the error back to the

106parent workflow.59parent workflow.

107 60 

108Codex also reapplies the parent turn’s live runtime overrides when it spawns a61Codex also reapplies the parent turn's live runtime overrides when it spawns a

109child. That includes sandbox and approval choices you set interactively during62child. That includes sandbox and approval choices you set interactively during

110the session, such as `/approvals` changes or `--yolo`, even if the selected63the session, such as `/approvals` changes or `--yolo`, even if the selected

111agent role loads a config file with different defaults.64custom agent file sets different defaults.

112 65 

113You can also override the sandbox configuration for individual [agent roles](#agent-roles) such as explicitly marking an agent to work in read-only mode.66You can also override the sandbox configuration for individual [custom agents](#custom-agents), such as explicitly marking one to work in read-only mode.

114 67 

115## Agent roles68## Custom agents

116 69 

117You configure agent roles in the `[agents]` section of your [configuration](https://developers.openai.com/codex/config-basic#configuration-precedence).70Codex ships with built-in agents:

118 71 

119Define agent roles either in your local configuration (typically `~/.codex/config.toml`) or in a project-specific `.codex/config.toml`.72- `default`: general-purpose fallback agent.

73- `worker`: execution-focused agent for implementation and fixes.

74- `explorer`: read-heavy codebase exploration agent.

120 75 

121Each role can provide guidance (`description`) for when Codex should use this agent, and optionally load a76To define your own custom agents, add standalone TOML files under

122role-specific config file (`config_file`) when Codex spawns an agent with that role.77`~/.codex/agents/` for personal agents or `.codex/agents/` for project-scoped

78agents.

123 79 

124Codex ships with built-in roles:80Each file defines one custom agent. Codex loads these files as configuration

81layers for spawned sessions, so custom agents can override the same settings as

82a normal Codex session config. That can feel heavier than a dedicated agent

83manifest, and the format may evolve as authoring and sharing mature.

125 84 

126- `default`: general-purpose fallback role.85Every standalone custom agent file must define:

127- `worker`: execution-focused role for implementation and fixes.

128- `explorer`: read-heavy codebase exploration role.

129- `monitor`: long-running command/task monitoring role (optimized for waiting/polling).

130 86 

131Each agent role can override your default configuration. Common settings to override for an agent role are:87- `name`

88- `description`

89- `developer_instructions`

132 90 

133- `model` and `model_reasoning_effort` to select a specific model for your agent role91Optional fields such as `nickname_candidates`, `model`,

134- `sandbox_mode` to mark an agent as `read-only`92`model_reasoning_effort`, `sandbox_mode`, `mcp_servers`, and `skills.config`

135- `developer_instructions` to give the agent role extra instructions without relying on the parent agent to pass them93inherit from the parent session when you omit them.

136 94 

137### Schema95### Global settings

96 

97Global subagent settings still live under `[agents]` in your [configuration](https://developers.openai.com/codex/config-basic#configuration-precedence).

138 98 

139| Field | Type | Required | Purpose |99| Field | Type | Required | Purpose |

140| --- | --- | --- | --- |100| --- | --- | --- | --- |

141| `agents.max_threads` | number | No | Concurrent open agent thread cap. |101| `agents.max_threads` | number | No | Concurrent open agent thread cap. |

142| `agents.max_depth` | number | No | Spawned agent nesting depth (root session starts at 0). |102| `agents.max_depth` | number | No | Spawned agent nesting depth (root session starts at 0). |

143| `agents.job_max_runtime_seconds` | number | No | Default timeout per worker for `spawn_agents_on_csv` jobs. |103| `agents.job_max_runtime_seconds` | number | No | Default timeout per worker for `spawn_agents_on_csv` jobs. |

144| `[agents.<name>]` | table | No | Role declaration. `<name>` becomes the `agent_type` when spawning an agent. |

145| `agents.<name>.description` | string | No | Human-facing role guidance shown to Codex when it decides which role to use. |

146| `agents.<name>.config_file` | string (path) | No | Path to a TOML config layer applied to spawned agents for that role. |

147 104 

148**Notes:**105**Notes:**

149 106 

150- Codex rejects unknown fields in `[agents.<name>]`.

151- `agents.max_threads` defaults to `6` when you leave it unset.107- `agents.max_threads` defaults to `6` when you leave it unset.

152- `agents.max_depth` defaults to `1`, which allows a direct child agent to spawn but prevents deeper nesting.108- `agents.max_depth` defaults to `1`, which allows a direct child agent to spawn but prevents deeper nesting.

153- `agents.job_max_runtime_seconds` is optional. When you leave it unset, `spawn_agents_on_csv` falls back to its per-call default timeout of 1800 seconds per worker.109- `agents.job_max_runtime_seconds` is optional. When you leave it unset, `spawn_agents_on_csv` falls back to its per-call default timeout of 1800 seconds per worker.

154- Codex resolves relative `config_file` paths relative to the `config.toml` file that defines the role.110- If a custom agent name matches a built-in agent such as `explorer`, your custom agent takes precedence.

155- Codex validates `agents.<name>.config_file` at config load time, and it must point to an existing file.111 

156- If a role name matches a built-in role (for example, `explorer`), your user-defined role takes precedence.112### Custom agent file schema

157- If Codex can’t load a role config file, agent spawns can fail until you fix the file.113 

158- The agent inherits any configuration that the role doesn’t set from the parent session.114| Field | Type | Required | Purpose |

115| --- | --- | --- | --- |

116| `name` | string | Yes | Agent name Codex uses when spawning or referring to this agent. |

117| `description` | string | Yes | Human-facing guidance for when Codex should use this agent. |

118| `developer_instructions` | string | Yes | Core instructions that define the agent's behavior. |

119| `nickname_candidates` | string[] | No | Optional pool of display nicknames for spawned agents. |

120 

121You can also include other supported `config.toml` keys in a custom agent file, such as `model`, `model_reasoning_effort`, `sandbox_mode`, `mcp_servers`, and `skills.config`.

122 

123Codex identifies the custom agent by its `name` field. Matching the filename to

124the agent name is the simplest convention, but the `name` field is the source

125of truth.

126 

127### Display nicknames

128 

129Use `nickname_candidates` when you want Codex to assign more readable display

130names to spawned agents. This is especially helpful when you run many

131instances of the same custom agent and want the UI to show distinct labels

132instead of repeating the same agent name.

133 

134Nicknames are presentation-only. Codex still identifies and spawns the agent by

135its `name`.

136 

137Nickname candidates must be a non-empty list of unique names. Each nickname can

138use ASCII letters, digits, spaces, hyphens, and underscores.

139 

140Example:

141 

142```toml

143name = "reviewer"

144description = "PR reviewer focused on correctness, security, and missing tests."

145developer_instructions = """

146Review code like an owner.

147Prioritize correctness, security, behavior regressions, and missing test coverage.

148"""

149nickname_candidates = ["Atlas", "Delta", "Echo"]

150```

151 

152In practice, the Codex app and CLI can show the nicknames where agent activity

153appears, while the underlying agent type stays

154`reviewer`.

159 155 

160### Example agent roles156### Example custom agents

161 157 

162The best role definitions are narrow and opinionated. Give each role one clear job, a tool surface that matches that job, and instructions that keep it from drifting into adjacent work.158The best custom agents are narrow and opinionated. Give each one clear job, a

159tool surface that matches that job, and instructions that keep it from

160drifting into adjacent work.

163 161 

164#### Example 1: PR review team162#### Example 1: PR review

165 163 

166This pattern splits review into three focused roles:164This pattern splits review across three focused custom agents:

167 165 

168- `explorer` maps the codebase and gathers evidence.166- `pr_explorer` maps the codebase and gathers evidence.

169- `reviewer` looks for correctness, security, and test risks.167- `reviewer` looks for correctness, security, and test risks.

170- `docs_researcher` checks framework or API documentation through a dedicated MCP server.168- `docs_researcher` checks framework or API documentation through a dedicated MCP server.

171 169 

172Project config (`.codex/config.toml`):170Project config (`.codex/config.toml`):

173 171 

174```172```toml

175[agents]173[agents]

176max_threads = 6174max_threads = 6

177max_depth = 1175max_depth = 1

178 

179[agents.explorer]

180description = "Read-only codebase explorer for gathering evidence before changes are proposed."

181config_file = "agents/explorer.toml"

182 

183[agents.reviewer]

184description = "PR reviewer focused on correctness, security, and missing tests."

185config_file = "agents/reviewer.toml"

186 

187[agents.docs_researcher]

188description = "Documentation specialist that uses the docs MCP server to verify APIs and framework behavior."

189config_file = "agents/docs-researcher.toml"

190```176```

191 177 

192`agents/explorer.toml`:178`.codex/agents/pr-explorer.toml`:

193 179 

194```180```toml

181name = "pr_explorer"

182description = "Read-only codebase explorer for gathering evidence before changes are proposed."

195model = "gpt-5.3-codex-spark"183model = "gpt-5.3-codex-spark"

196model_reasoning_effort = "medium"184model_reasoning_effort = "medium"

197sandbox_mode = "read-only"185sandbox_mode = "read-only"

202"""190"""

203```191```

204 192 

205`agents/reviewer.toml`:193`.codex/agents/reviewer.toml`:

206 194 

207```195```toml

208model = "gpt-5.3-codex"196name = "reviewer"

197description = "PR reviewer focused on correctness, security, and missing tests."

198model = "gpt-5.4"

209model_reasoning_effort = "high"199model_reasoning_effort = "high"

210sandbox_mode = "read-only"200sandbox_mode = "read-only"

211developer_instructions = """201developer_instructions = """

215"""205"""

216```206```

217 207 

218`agents/docs-researcher.toml`:208`.codex/agents/docs-researcher.toml`:

219 209 

220```210```toml

211name = "docs_researcher"

212description = "Documentation specialist that uses the docs MCP server to verify APIs and framework behavior."

221model = "gpt-5.3-codex-spark"213model = "gpt-5.3-codex-spark"

222model_reasoning_effort = "medium"214model_reasoning_effort = "medium"

223sandbox_mode = "read-only"215sandbox_mode = "read-only"

233 225 

234This setup works well for prompts like:226This setup works well for prompts like:

235 227 

228```text

229Review this branch against main. Have pr_explorer map the affected code paths, reviewer find real risks, and docs_researcher verify the framework APIs that the patch relies on.

236```230```

237Review this branch against main. Have explorer map the affected code paths, reviewer find real risks, and docs_researcher verify the framework APIs that the patch relies on.231 

232## Process CSV batches with subagents (experimental)

233 

234This workflow is experimental and may change as subagent support evolves.

235Use `spawn_agents_on_csv` when you have many similar tasks that map to one row per work item. Codex reads the CSV, spawns one worker subagent per row, waits for the full batch to finish, and exports the combined results to CSV.

236 

237This works well for repeated audits such as:

238 

239- reviewing one file, package, or service per row

240- checking a list of incidents, PRs, or migration targets

241- generating structured summaries for many similar inputs

242 

243The tool accepts:

244 

245- `csv_path` for the source CSV

246- `instruction` for the worker prompt template, using `{column_name}` placeholders

247- `id_column` when you want stable item ids from a specific column

248- `output_schema` when each worker should return a JSON object with a fixed shape

249- `output_csv_path`, `max_concurrency`, and `max_runtime_seconds` for job control

250 

251Each worker must call `report_agent_job_result` exactly once. If a worker exits without reporting a result, Codex marks that row with an error in the exported CSV.

252 

253Example prompt:

254 

255```text

256Create /tmp/components.csv with columns path,owner and one row per frontend component.

257 

258Then call spawn_agents_on_csv with:

259- csv_path: /tmp/components.csv

260- id_column: path

261- instruction: "Review {path} owned by {owner}. Return JSON with keys path, risk, summary, and follow_up via report_agent_job_result."

262- output_csv_path: /tmp/components-review.csv

263- output_schema: an object with required string fields path, risk, summary, and follow_up

238```264```

239 265 

240#### Example 2: Frontend integration debugging team266When you run this through `codex exec`, Codex shows a single-line progress update on `stderr` while the batch is running. The exported CSV includes the original row data plus metadata such as `job_id`, `item_id`, `status`, `last_error`, and `result_json`.

267 

268Related runtime settings:

269 

270- `agents.max_threads` caps how many agent threads can stay open concurrently.

271- `agents.job_max_runtime_seconds` sets the default per-worker timeout for CSV fan-out jobs. A per-call `max_runtime_seconds` override takes precedence.

272- `sqlite_home` controls where Codex stores the SQLite-backed state used for agent jobs and their exported results.

273 

274#### Example 2: Frontend integration debugging

241 275 

242This pattern is useful for UI regressions, flaky browser flows, or integration bugs that cross application code and the running product.276This pattern is useful for UI regressions, flaky browser flows, or integration bugs that cross application code and the running product.

243 277 

244Project config (`.codex/config.toml`):278Project config (`.codex/config.toml`):

245 279 

246```280```toml

247[agents]281[agents]

248max_threads = 6282max_threads = 6

249max_depth = 1283max_depth = 1

250 

251[agents.explorer]

252description = "Read-only codebase explorer for locating the relevant frontend and backend code paths."

253config_file = "agents/explorer.toml"

254 

255[agents.browser_debugger]

256description = "UI debugger that uses browser tooling to reproduce issues and capture evidence."

257config_file = "agents/browser-debugger.toml"

258 

259[agents.worker]

260description = "Implementation-focused agent for small, targeted fixes after the issue is understood."

261config_file = "agents/worker.toml"

262```284```

263 285 

264`agents/explorer.toml`:286`.codex/agents/code-mapper.toml`:

265 287 

266```288```toml

289name = "code_mapper"

290description = "Read-only codebase explorer for locating the relevant frontend and backend code paths."

267model = "gpt-5.3-codex-spark"291model = "gpt-5.3-codex-spark"

268model_reasoning_effort = "medium"292model_reasoning_effort = "medium"

269sandbox_mode = "read-only"293sandbox_mode = "read-only"

273"""297"""

274```298```

275 299 

276`agents/browser-debugger.toml`:300`.codex/agents/browser-debugger.toml`:

277 301 

278```302```toml

279model = "gpt-5.3-codex"303name = "browser_debugger"

304description = "UI debugger that uses browser tooling to reproduce issues and capture evidence."

305model = "gpt-5.4"

280model_reasoning_effort = "high"306model_reasoning_effort = "high"

281sandbox_mode = "workspace-write"307sandbox_mode = "workspace-write"

282developer_instructions = """308developer_instructions = """

290startup_timeout_sec = 20316startup_timeout_sec = 20

291```317```

292 318 

293`agents/worker.toml`:319`.codex/agents/ui-fixer.toml`:

294 320 

295```321```toml

296model = "gpt-5.3-codex"322name = "ui_fixer"

323description = "Implementation-focused agent for small, targeted fixes after the issue is understood."

324model = "gpt-5.3-codex-spark"

297model_reasoning_effort = "medium"325model_reasoning_effort = "medium"

298developer_instructions = """326developer_instructions = """

299Own the fix once the issue is reproduced.327Own the fix once the issue is reproduced.

307 335 

308This setup works well for prompts like:336This setup works well for prompts like:

309 337 

310```338```text

311Investigate why the settings modal fails to save. Have browser_debugger reproduce it, explorer trace the responsible code path, and worker implement the smallest fix once the failure mode is clear.339Investigate why the settings modal fails to save. Have browser_debugger reproduce it, code_mapper trace the responsible code path, and ui_fixer implement the smallest fix once the failure mode is clear.

312```340```