multi-agent.md Codex Docs, 2026-02-23 18:27 UTC → 2026-02-27 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.

35 

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

35 37 

36```38```

47 49 

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

49- 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).

50 53 

51## Approvals and sandbox controls54## Approvals and sandbox controls

52 55 

68 71 

69Codex ships with built-in roles:72Codex ships with built-in roles:

70 73 

71- `default`74- `default`: general-purpose fallback role.

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

73- `explorer`76- `explorer`: read-heavy codebase exploration role.

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

74 78 

75Each agent role can override your default configuration. Common settings to override for an agent role are:79Each agent role can override your default configuration. Common settings to override for an agent role are:

76 80 

83| Field | Type | Required | Purpose |87| Field | Type | Required | Purpose |

84| --- | --- | --- | --- |88| --- | --- | --- | --- |

85| `agents.max_threads` | number | No | Maximum number of concurrently open agent threads. |89| `agents.max_threads` | number | No | Maximum number of concurrently open agent threads. |

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

86| `[agents.<name>]` | table | No | Declares a role. `<name>` is used as the `agent_type` when spawning an agent. |91| `[agents.<name>]` | table | No | Declares a role. `<name>` is used as the `agent_type` when spawning an agent. |

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

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

90**Notes:**95**Notes:**

91 96 

92- Unknown fields in `[agents.<name>]` are rejected.97- Unknown fields in `[agents.<name>]` are rejected.

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

93- Relative `config_file` paths are resolved relative to the `config.toml` file that defines the role.99- Relative `config_file` paths are resolved relative to the `config.toml` file that defines the role.

100- `agents.<name>.config_file` is validated at config load time and must point to an existing file.

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

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

96- Any configuration not set by the agent role will be inherited from the parent session.103- Any configuration not set by the agent role will be inherited from the parent session.

97 104 

98### Example agent roles105### Example agent roles

99 106 

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

109#### Example 1: PR review team

110 

111This pattern splits review into three focused roles:

112 

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

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

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

101 116 

102Example `~/.codex/config.toml`:117Project config (`.codex/config.toml`):

103 118 

104```119```

105[agents.default]120[agents]

106description = "General-purpose helper."121max_threads = 6

122max_depth = 1

123 

124[agents.explorer]

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

126config_file = "agents/explorer.toml"

107 127 

108[agents.reviewer]128[agents.reviewer]

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

110config_file = "agents/reviewer.toml"130config_file = "agents/reviewer.toml"

111 131 

112[agents.explorer]132[agents.docs_researcher]

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

114config_file = "agents/custom-explorer.toml"134config_file = "agents/docs-researcher.toml"

135```

136 

137`agents/explorer.toml`:

138 

139```

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

141model_reasoning_effort = "medium"

142sandbox_mode = "read-only"

143developer_instructions = """

144Stay in exploration mode.

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

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

147"""

115```148```

116 149 

117Example config file for the `reviewer` role (`~/.codex/agents/reviewer.toml`):150`agents/reviewer.toml`:

118 151 

119```152```

120model = "gpt-5.3-codex"153model = "gpt-5.3-codex"

121model_reasoning_effort = "high"154model_reasoning_effort = "high"

122developer_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."155sandbox_mode = "read-only"

156developer_instructions = """

157Review code like an owner.

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

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

160"""

161```

162 

163`agents/docs-researcher.toml`:

164 

165```

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

167model_reasoning_effort = "medium"

168sandbox_mode = "read-only"

169developer_instructions = """

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

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

172Do not make code changes.

173"""

174 

175[mcp_servers.openaiDeveloperDocs]

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

177```

178 

179This setup works well for prompts like:

180 

181```

182Review 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.

123```183```

124 184 

125Example config file for the `explorer` role (`~/.codex/agents/custom-explorer.toml`):185#### Example 2: frontend integration debugging team

186 

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

188 

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

190 

191```

192[agents]

193max_threads = 6

194max_depth = 1

195 

196[agents.explorer]

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

198config_file = "agents/explorer.toml"

199 

200[agents.browser_debugger]

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

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

203 

204[agents.worker]

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

206config_file = "agents/worker.toml"

207```

208 

209`agents/explorer.toml`:

126 210 

127```211```

128model = "gpt-5.3-codex-spark"212model = "gpt-5.3-codex-spark"

129model_reasoning_effort = "medium"213model_reasoning_effort = "medium"

130sandbox_mode = "read-only"214sandbox_mode = "read-only"

215developer_instructions = """

216Map the code that owns the failing UI flow.

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

218"""

219```

220 

221`agents/browser-debugger.toml`:

222 

223```

224model = "gpt-5.3-codex"

225model_reasoning_effort = "high"

226sandbox_mode = "workspace-write"

227developer_instructions = """

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

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

230Do not edit application code.

231"""

232 

233[mcp_servers.chrome_devtools]

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

235startup_timeout_sec = 20

236```

237 

238`agents/worker.toml`:

239 

240```

241model = "gpt-5.3-codex"

242model_reasoning_effort = "medium"

243developer_instructions = """

244Own the fix once the issue is reproduced.

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

246"""

247 

248[[skills.config]]

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

250enabled = false

251```

252 

253This setup works well for prompts like:

254 

255```

256Investigate 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.

131```257```