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.
65
66You can also override the sandbox configuration for individual [custom agents](#custom-agents), such as explicitly marking one to work in read-only mode.
112 67
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.68## Custom agents
114 69
115## Agent roles70Codex ships with built-in agents:
116 71
117You configure agent roles in the `[agents]` section of your [configuration](https://developers.openai.com/codex/config-basic#configuration-precedence).72- `default`: general-purpose fallback agent.
73- `worker`: execution-focused agent for implementation and fixes.
74- `explorer`: read-heavy codebase exploration agent.
118 75
119Define agent roles either in your local configuration (typically `~/.codex/config.toml`) or in a project-specific `.codex/config.toml`.76To define your own custom agents, add standalone TOML files under
77`~/.codex/agents/` for personal agents or `.codex/agents/` for project-scoped
78agents.
120 79
121Each role can provide guidance (`description`) for when Codex should use this agent, and optionally load a80Each file defines one custom agent. Codex loads these files as configuration
122role-specific config file (`config_file`) when Codex spawns an agent with that role.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.
123 84
124Codex ships with built-in roles:85Every standalone custom agent file must define:
125 86
126- `default`: general-purpose fallback role.87- `name`
127- `worker`: execution-focused role for implementation and fixes.88- `description`
128- `explorer`: read-heavy codebase exploration role.89- `developer_instructions`
129- `monitor`: long-running command/task monitoring role (optimized for waiting/polling).
130 90
131Each agent role can override your default configuration. Common settings to override for an agent role are:91Optional fields such as `nickname_candidates`, `model`,
92`model_reasoning_effort`, `sandbox_mode`, `mcp_servers`, and `skills.config`
93inherit from the parent session when you omit them.
132 94
133- `model` and `model_reasoning_effort` to select a specific model for your agent role95### Global settings
134- `sandbox_mode` to mark an agent as `read-only`
135- `developer_instructions` to give the agent role extra instructions without relying on the parent agent to pass them
136 96
137### Schema97Global 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. |
159 120
160### Example agent roles121You 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`.
161 122
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.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.
163 126
164#### Example 1: PR review team127### Display nicknames
165 128
166This pattern splits review into three focused roles: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.
167 133
168- `explorer` maps the codebase and gathers evidence.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`.
155
156### Example custom agents
157
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.
161
162#### Example 1: PR review
163
164This pattern splits review across three focused custom agents:
165
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
221model = "gpt-5.3-codex-spark"211name = "docs_researcher"
212description = "Documentation specialist that uses the docs MCP server to verify APIs and framework behavior."
213model = "gpt-5.4-mini"
222model_reasoning_effort = "medium"214model_reasoning_effort = "medium"
223sandbox_mode = "read-only"215sandbox_mode = "read-only"
224developer_instructions = """216developer_instructions = """
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
267model = "gpt-5.3-codex-spark"289name = "code_mapper"
290description = "Read-only codebase explorer for locating the relevant frontend and backend code paths."
291model = "gpt-5.4-mini"
268model_reasoning_effort = "medium"292model_reasoning_effort = "medium"
269sandbox_mode = "read-only"293sandbox_mode = "read-only"
270developer_instructions = """294developer_instructions = """
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```
