multi-agent.md Codex Docs, 2026-02-24 00:33 UTC → 2026-03-13 18:15 UTC

31 31 

32Codex will automatically decide when to spawn a new agent or you can explicitly ask it to do so.32Codex will automatically decide when to spawn a new agent or you can explicitly ask it to do so.

33 33 

34For long-running commands or polling workflows, Codex can also use the built-in `monitor` role, which is tuned for waiting and repeated status checks.34For long-running commands or polling workflows, Codex can also use the built-in `monitor` role, tuned for waiting and repeated status checks.

35 35 

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

37 37 

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

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

53 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 

54## Approvals and sandbox controls95## Approvals and sandbox controls

55 96 

56Sub-agents inherit your current sandbox policy, but they run with97Sub-agents inherit your current sandbox policy.

57non-interactive approvals. If a sub-agent attempts an action that would require98 

58a new approval, that action fails and the error is surfaced in the parent99In interactive CLI sessions, approval requests can surface from inactive agent

59workflow.100threads 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 before

102you approve, reject, or answer the request.

103 

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

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

106parent workflow.

107 

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

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

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

111agent role loads a config file with different defaults.

60 112 

61You can also override the sandbox configuration for individual [agent roles](#agent-roles) such as explicitly marking an agent to work in read-only mode.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.

62 114 

64 116 

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

66 118 

67Agent roles can be defined either in your local configuration (typically `~/.codex/config.toml`) or shared in a project-specific `.codex/config.toml`.119Define agent roles either in your local configuration (typically `~/.codex/config.toml`) or in a project-specific `.codex/config.toml`.

68 120 

69Each role can provide guidance (`description`) for when Codex should use this agent, and optionally load a121Each role can provide guidance (`description`) for when Codex should use this agent, and optionally load a

70role-specific config file (`config_file`) when Codex spawns an agent with that role.122role-specific config file (`config_file`) when Codex spawns an agent with that role.

80 132 

81- `model` and `model_reasoning_effort` to select a specific model for your agent role133- `model` and `model_reasoning_effort` to select a specific model for your agent role

82- `sandbox_mode` to mark an agent as `read-only`134- `sandbox_mode` to mark an agent as `read-only`

83- `developer_instructions` to give the agent role additional instructions without relying on the parent agent for passing them135- `developer_instructions` to give the agent role extra instructions without relying on the parent agent to pass them

84 136 

85### Schema137### Schema

86 138 

87| Field | Type | Required | Purpose |139| Field | Type | Required | Purpose |

88| --- | --- | --- | --- |140| --- | --- | --- | --- |

89| `agents.max_threads` | number | No | Maximum number of concurrently open agent threads. |141| `agents.max_threads` | number | No | Concurrent open agent thread cap. |

90| `agents.max_depth` | number | No | Maximum nesting depth for spawned agent threads (root session starts at 0). |142| `agents.max_depth` | number | No | Spawned agent nesting depth (root session starts at 0). |

91| `[agents.<name>]` | table | No | Declares a role. `<name>` is used as the `agent_type` when spawning an agent. |143| `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. |

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

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

94 147 

95**Notes:**148**Notes:**

96 149 

97- Unknown fields in `[agents.<name>]` are rejected.150- Codex rejects unknown fields in `[agents.<name>]`.

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

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

99- Relative `config_file` paths are resolved relative to the `config.toml` file that defines the role.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.

100- `agents.<name>.config_file` is validated at config load time and must point to an existing file.154- Codex resolves relative `config_file` paths relative to the `config.toml` file that defines the role.

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

101- If a role name matches a built-in role (for example, `explorer`), your user-defined role takes precedence.156- If a role name matches a built-in role (for example, `explorer`), your user-defined role takes precedence.

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

103- Any configuration not set by the agent role will be inherited from the parent session.158- The agent inherits any configuration that the role doesn’t set from the parent session.

104 159 

105### Example agent roles160### Example agent roles

106 161 

107Below is an example that overrides the definitions for the built-in `default` and `explorer` agent roles and defines a new `reviewer` role.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.

108 163 

109Example `~/.codex/config.toml`:164#### Example 1: PR review team

165 

166This pattern splits review into three focused roles:

167 

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

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

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

171 

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

110 173 

111```174```

112[agents.default]175[agents]

113description = "General-purpose helper."176max_threads = 6

177max_depth = 1

178 

179[agents.explorer]

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

181config_file = "agents/explorer.toml"

114 182 

115[agents.reviewer]183[agents.reviewer]

116description = "Find security, correctness, and test risks in code."184description = "PR reviewer focused on correctness, security, and missing tests."

117config_file = "agents/reviewer.toml"185config_file = "agents/reviewer.toml"

118 186 

119[agents.explorer]187[agents.docs_researcher]

120description = "Fast codebase explorer for read-heavy tasks."188description = "Documentation specialist that uses the docs MCP server to verify APIs and framework behavior."

121config_file = "agents/custom-explorer.toml"189config_file = "agents/docs-researcher.toml"

122```190```

123 191 

124Example config file for the `reviewer` role (`~/.codex/agents/reviewer.toml`):192`agents/explorer.toml`:

193 

194```

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

196model_reasoning_effort = "medium"

197sandbox_mode = "read-only"

198developer_instructions = """

199Stay in exploration mode.

200Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks for them.

201Prefer fast search and targeted file reads over broad scans.

202"""

203```

204 

205`agents/reviewer.toml`:

125 206 

126```207```

127model = "gpt-5.3-codex"208model = "gpt-5.3-codex"

128model_reasoning_effort = "high"209model_reasoning_effort = "high"

129developer_instructions = "Focus on high priority issues, write tests to validate hypothesis before flagging an issue. When finding security issues give concrete steps on how to reproduce the vulnerability."210sandbox_mode = "read-only"

211developer_instructions = """

212Review code like an owner.

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

214Lead with concrete findings, include reproduction steps when possible, and avoid style-only comments unless they hide a real bug.

215"""

216```

217 

218`agents/docs-researcher.toml`:

219 

220```

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

222model_reasoning_effort = "medium"

223sandbox_mode = "read-only"

224developer_instructions = """

225Use the docs MCP server to confirm APIs, options, and version-specific behavior.

226Return concise answers with links or exact references when available.

227Do not make code changes.

228"""

229 

230[mcp_servers.openaiDeveloperDocs]

231url = "https://developers.openai.com/mcp"

232```

233 

234This setup works well for prompts like:

235 

236```

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.

238```

239 

240#### Example 2: Frontend integration debugging team

241 

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

243 

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

245 

246```

247[agents]

248max_threads = 6

249max_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"

130```262```

131 263 

132Example config file for the `explorer` role (`~/.codex/agents/custom-explorer.toml`):264`agents/explorer.toml`:

133 265 

134```266```

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

136model_reasoning_effort = "medium"268model_reasoning_effort = "medium"

137sandbox_mode = "read-only"269sandbox_mode = "read-only"

270developer_instructions = """

271Map the code that owns the failing UI flow.

272Identify entry points, state transitions, and likely files before the worker starts editing.

273"""

274```

275 

276`agents/browser-debugger.toml`:

277 

278```

279model = "gpt-5.3-codex"

280model_reasoning_effort = "high"

281sandbox_mode = "workspace-write"

282developer_instructions = """

283Reproduce the issue in the browser, capture exact steps, and report what the UI actually does.

284Use browser tooling for screenshots, console output, and network evidence.

285Do not edit application code.

286"""

287 

288[mcp_servers.chrome_devtools]

289url = "http://localhost:3000/mcp"

290startup_timeout_sec = 20

291```

292 

293`agents/worker.toml`:

294 

295```

296model = "gpt-5.3-codex"

297model_reasoning_effort = "medium"

298developer_instructions = """

299Own the fix once the issue is reproduced.

300Make the smallest defensible change, keep unrelated files untouched, and validate only the behavior you changed.

301"""

302 

303[[skills.config]]

304path = "/Users/me/.agents/skills/docs-editor/SKILL.md"

305enabled = false

306```

307 

308This setup works well for prompts like:

309 

310```

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.

138```312```