Documentation 2026-07-21 22:02 UTC to 2026-07-22 20:02 UTC

114For most tasks in Codex, start with 114For most tasks in Codex, start with

115 `gpt-5.6`. Use 115 `gpt-5.6`. Use

116 `gpt-5.6-terra` when you want116 `gpt-5.6-terra` when you want

117 a faster, lower-cost option for lighter subagent work. If you have ChatGPT Pro117 a faster, lower-cost option for lighter subagent work.

118 and want near-instant text-only iteration, `gpt-5.3-codex-spark` remains

119 available in research preview.

120 118 

121### Model choice119### Model choice

122 120 

123- **`gpt-5.6`**: Start here for demanding agents. It's strongest for ambiguous, multi-step work that needs planning, tool use, validation, and follow-through across a larger context.121- **`gpt-5.6`**: Start here for demanding agents. It's strongest for ambiguous, multi-step work that needs planning, tool use, validation, and follow-through across a larger context.

124- **`gpt-5.4`**: Use this when a workflow is pinned to GPT-5.4. It combines strong coding, reasoning, tool use, and broader workflows.122- **`gpt-5.4`**: Use this when a workflow is pinned to GPT-5.4. It combines strong coding, reasoning, tool use, and broader workflows.

125- **`gpt-5.6-terra`**: Use for agents that favor speed and efficiency over depth, such as exploration, read-heavy scans, large-file review, or processing supporting documents. It works well for parallel workers that return distilled results to the main agent.123- **`gpt-5.6-terra`**: Use for agents that favor speed and efficiency over depth, such as exploration, read-heavy scans, large-file review, or processing supporting documents. It works well for parallel workers that return distilled results to the main agent.

126- **`gpt-5.3-codex-spark`**: If you have ChatGPT Pro, use this research preview model for near-instant, text-only iteration when latency matters more than broader capability.

127 124 

128### Reasoning effort (`model_reasoning_effort`)125### Reasoning effort (`model_reasoning_effort`)

129 126 

134- **`high`**: Use when an agent needs to trace complex logic, check assumptions, or work through edge cases (for example, reviewer or security-focused agents).131- **`high`**: Use when an agent needs to trace complex logic, check assumptions, or work through edge cases (for example, reviewer or security-focused agents).

135- **`medium`**: A balanced default for most agents.132- **`medium`**: A balanced default for most agents.

136- **`low`**: Use when the task is straightforward and speed matters most.133- **`low`**: Use when the task is straightforward and speed matters most.

137- **`minimal`** and **`none`**: Use when the selected model supports these

138 lower-latency levels and the task needs little or no reasoning.

139 134 

140Higher reasoning effort increases response time and token usage, but it can improve quality for complex work. For details, see [Models](https://learn.chatgpt.com/docs/models), [Config basics](https://learn.chatgpt.com/docs/config-file/config-basic), and [Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-reference).135Higher reasoning effort increases response time and token usage, but it can improve quality for complex work. For details, see [Models](https://learn.chatgpt.com/docs/models), [Config basics](https://learn.chatgpt.com/docs/config-file/config-basic), and [Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-reference).

141 136 

142<code>agents.max_depth</code> controls nesting and defaults to <code>1</code>,

143 which lets the root thread spawn direct children but prevents those children

144 from spawning deeper descendants.

145 

146 137 

147 138 

148## Orchestration and thread controls139## Orchestration and thread controls

252- `description`243- `description`

253- `developer_instructions`244- `developer_instructions`

254 245 

255Optional fields such as `nickname_candidates`, `model`,246If a custom agent file sets `model` or `model_reasoning_effort`, the value in

256`model_reasoning_effort`, `sandbox_mode`, `mcp_servers`, and `skills.config`247the file takes precedence. Otherwise, Codex resolves each setting independently:

257inherit from the parent session when you omit them.248an explicit spawn value, then the corresponding `[agents]` default, then the

249parent's value. If a spawn selects a different model and neither an explicit nor

250configured effort is present, Codex uses that model's default effort. Other

251session settings, such as `sandbox_mode`, `mcp_servers`, and `skills.config`,

252inherit from the parent when the custom agent file omits them.

258 253 

259### Global settings254### Global settings

260 255 

261Global subagent settings still live under `[agents]` in your [configuration](https://learn.chatgpt.com/docs/config-file/config-basic#configuration-precedence).256Global subagent settings still live under `[agents]` in your [configuration](https://learn.chatgpt.com/docs/config-file/config-basic#configuration-precedence).

262 257 

263| Field | Type | Required | Purpose |258| Field | Type | Required | Purpose |

264| -------------------------------- | ------- | :------: | ----------------------------------------------------------------- |259| ------------------------------------------- | ------- | :------: | ------------------------------------------------------------------- |

265| `agents.max_threads` | number | No | Concurrent open agent thread cap. |260| `agents.enabled` | boolean | No | Enable or disable multi-agent tools. |

266| `agents.max_depth` | number | No | Spawned agent nesting depth (root session starts at 0). |261| `agents.max_concurrent_threads_per_session` | number | No | Cap concurrently open spawned-agent threads, excluding the primary. |

267| `agents.job_max_runtime_seconds` | number | No | Default timeout per worker for `spawn_agents_on_csv` jobs. |262| `agents.default_subagent_model` | string | No | Set the default model for spawned agents. |

263| `agents.default_subagent_reasoning_effort` | string | No | Set the default reasoning effort for spawned agents. |

268| `agents.interrupt_message` | boolean | No | Record a model-visible message when an agent turn is interrupted. |264| `agents.interrupt_message` | boolean | No | Record a model-visible message when an agent turn is interrupted. |

269 265 

270**Notes:**266**Notes:**

271 267 

272- `agents.max_threads` defaults to `6` when you leave it unset.268- `agents.enabled` defaults to `true`. Set it to `false` to disable multi-agent tools.

273- `agents.max_depth` defaults to `1`, which lets the root thread spawn direct children but prevents those children from spawning deeper descendants. Keep the default unless you specifically need recursive delegation. Raising this value can turn broad delegation instructions into repeated fan-out, which increases token usage, latency, and local resource consumption. `agents.max_threads` still caps concurrent open threads, but it doesn't remove the cost and predictability risks of deeper recursion.269- When you leave `agents.max_concurrent_threads_per_session` unset, Codex chooses the default. Existing configurations can keep using `agents.max_threads` as a legacy alias.

274- `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.270- Explicit spawn values override `agents.default_subagent_model` and `agents.default_subagent_reasoning_effort`.

275- `agents.interrupt_message` defaults to `true`. Set it to `false` to omit the model-visible interruption message from the agent's context.271- `agents.interrupt_message` defaults to `true`. Set it to `false` to omit the model-visible interruption message from the agent's context.

276- If a custom agent name matches a built-in agent such as `explorer`, your custom agent takes precedence.272- If a custom agent name matches a built-in agent such as `explorer`, your custom agent takes precedence.

277 273 

278### Custom agent file schema274### Custom agent file schema

279 275 

280| Field | Type | Required | Purpose |276| Field | Type | Required | Purpose |

281| ------------------------ | -------- | :------: | --------------------------------------------------------------- |277| ------------------------ | ------ | :------: | --------------------------------------------------------------- |

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

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

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

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

286 281 

287You 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`.282You 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`.

288 283 

290the agent name is the simplest convention, but the `name` field is the source285the agent name is the simplest convention, but the `name` field is the source

291of truth.286of truth.

292 287 

293### Display nicknames

294 

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

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

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

298instead of repeating the same agent name.

299 

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

301its `name`.

302 

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

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

305 

306Example:

307 

308```toml

309name = "reviewer"

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

311developer_instructions = """

312Review code like an owner.

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

314"""

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

316```

317 

318In practice, the ChatGPT desktop app, Codex CLI, and IDE extension can show the

319nicknames where agent activity appears, while the underlying agent type stays

320`reviewer`.

321 

322### Example custom agents288### Example custom agents

323 289 

324The best custom agents are narrow and opinionated. Give each one clear job, a290The best custom agents are narrow and opinionated. Give each one clear job, a

337 303 

338```toml304```toml

339[agents]305[agents]

340max_threads = 6306max_concurrent_threads_per_session = 8

341max_depth = 1

342```307```

343 308 

344`.codex/agents/pr-explorer.toml`:309`.codex/agents/pr-explorer.toml`:

395Review 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.360Review 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.

396```361```

397 362 

398## Process CSV batches with subagents (experimental)

399 

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

401Use `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.

402 

403This works well for repeated audits such as:

404 

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

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

407- generating structured summaries for many similar inputs

408 

409The tool accepts:

410 

411- `csv_path` for the source CSV

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

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

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

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

416 

417Each 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.

418 

419Example prompt:

420 

421```text

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

423 

424Then call spawn_agents_on_csv with:

425- csv_path: /tmp/components.csv

426- id_column: path

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

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

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

430```

431 

432When 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`.

433 

434Related runtime settings:

435 

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

437- `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.

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

439 

440#### Example 2: Frontend integration debugging363#### Example 2: Frontend integration debugging

441 364 

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

445 368 

446```toml369```toml

447[agents]370[agents]

448max_threads = 6371max_concurrent_threads_per_session = 6

449max_depth = 1

450```372```

451 373 

452`.codex/agents/code-mapper.toml`:374`.codex/agents/code-mapper.toml`:

119Skills can be global (in your user directory, for you as a developer) or repo-specific (checked into `.agents/skills`, for your team). Put repo skills in `.agents/skills` when the workflow applies to that project; use your user directory for skills you want across all repos.119Skills can be global (in your user directory, for you as a developer) or repo-specific (checked into `.agents/skills`, for your team). Put repo skills in `.agents/skills` when the workflow applies to that project; use your user directory for skills you want across all repos.

120 120 

121| Layer | Global | Repo |121| Layer | Global | Repo |

122| :----- | :--------------------- | :--------------------------------------------- |122| :----- | :------------------- | :--------------------------------------------- |

123| AGENTS | `~/.codex/AGENTS.md` | `AGENTS.md` in repo root or nested directories |123| AGENTS | `~/.codex/AGENTS.md` | `AGENTS.md` in repo root or nested directories |

124| Skills | `$HOME/.agents/skills` | `.agents/skills` in repo |124| Skills | `~/.agents/skills` | `.agents/skills` in repo |

125 125 

126Codex uses progressive disclosure for skills:126Codex uses progressive disclosure for skills:

127 127 

114For most tasks in Codex, start with 114For most tasks in Codex, start with

115 `gpt-5.6`. Use 115 `gpt-5.6`. Use

116 `gpt-5.6-terra` when you want116 `gpt-5.6-terra` when you want

117 a faster, lower-cost option for lighter subagent work. If you have ChatGPT Pro117 a faster, lower-cost option for lighter subagent work.

118 and want near-instant text-only iteration, `gpt-5.3-codex-spark` remains

119 available in research preview.

120 118 

121### Model choice119### Model choice

122 120 

123- **`gpt-5.6`**: Start here for demanding agents. It's strongest for ambiguous, multi-step work that needs planning, tool use, validation, and follow-through across a larger context.121- **`gpt-5.6`**: Start here for demanding agents. It's strongest for ambiguous, multi-step work that needs planning, tool use, validation, and follow-through across a larger context.

124- **`gpt-5.4`**: Use this when a workflow is pinned to GPT-5.4. It combines strong coding, reasoning, tool use, and broader workflows.122- **`gpt-5.4`**: Use this when a workflow is pinned to GPT-5.4. It combines strong coding, reasoning, tool use, and broader workflows.

125- **`gpt-5.6-terra`**: Use for agents that favor speed and efficiency over depth, such as exploration, read-heavy scans, large-file review, or processing supporting documents. It works well for parallel workers that return distilled results to the main agent.123- **`gpt-5.6-terra`**: Use for agents that favor speed and efficiency over depth, such as exploration, read-heavy scans, large-file review, or processing supporting documents. It works well for parallel workers that return distilled results to the main agent.

126- **`gpt-5.3-codex-spark`**: If you have ChatGPT Pro, use this research preview model for near-instant, text-only iteration when latency matters more than broader capability.

127 124 

128### Reasoning effort (`model_reasoning_effort`)125### Reasoning effort (`model_reasoning_effort`)

129 126 

134- **`high`**: Use when an agent needs to trace complex logic, check assumptions, or work through edge cases (for example, reviewer or security-focused agents).131- **`high`**: Use when an agent needs to trace complex logic, check assumptions, or work through edge cases (for example, reviewer or security-focused agents).

135- **`medium`**: A balanced default for most agents.132- **`medium`**: A balanced default for most agents.

136- **`low`**: Use when the task is straightforward and speed matters most.133- **`low`**: Use when the task is straightforward and speed matters most.

137- **`minimal`** and **`none`**: Use when the selected model supports these

138 lower-latency levels and the task needs little or no reasoning.

139 134 

140Higher reasoning effort increases response time and token usage, but it can improve quality for complex work. For details, see [Models](https://learn.chatgpt.com/docs/models), [Config basics](https://learn.chatgpt.com/docs/config-file/config-basic), and [Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-reference).135Higher reasoning effort increases response time and token usage, but it can improve quality for complex work. For details, see [Models](https://learn.chatgpt.com/docs/models), [Config basics](https://learn.chatgpt.com/docs/config-file/config-basic), and [Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-reference).

141 136 

142<code>agents.max_depth</code> controls nesting and defaults to <code>1</code>,

143 which lets the root thread spawn direct children but prevents those children

144 from spawning deeper descendants.

145 

146 137 

147 138 

148## Orchestration and thread controls139## Orchestration and thread controls

252- `description`243- `description`

253- `developer_instructions`244- `developer_instructions`

254 245 

255Optional fields such as `nickname_candidates`, `model`,246If a custom agent file sets `model` or `model_reasoning_effort`, the value in

256`model_reasoning_effort`, `sandbox_mode`, `mcp_servers`, and `skills.config`247the file takes precedence. Otherwise, Codex resolves each setting independently:

257inherit from the parent session when you omit them.248an explicit spawn value, then the corresponding `[agents]` default, then the

249parent's value. If a spawn selects a different model and neither an explicit nor

250configured effort is present, Codex uses that model's default effort. Other

251session settings, such as `sandbox_mode`, `mcp_servers`, and `skills.config`,

252inherit from the parent when the custom agent file omits them.

258 253 

259### Global settings254### Global settings

260 255 

261Global subagent settings still live under `[agents]` in your [configuration](https://learn.chatgpt.com/docs/config-file/config-basic#configuration-precedence).256Global subagent settings still live under `[agents]` in your [configuration](https://learn.chatgpt.com/docs/config-file/config-basic#configuration-precedence).

262 257 

263| Field | Type | Required | Purpose |258| Field | Type | Required | Purpose |

264| -------------------------------- | ------- | :------: | ----------------------------------------------------------------- |259| ------------------------------------------- | ------- | :------: | ------------------------------------------------------------------- |

265| `agents.max_threads` | number | No | Concurrent open agent thread cap. |260| `agents.enabled` | boolean | No | Enable or disable multi-agent tools. |

266| `agents.max_depth` | number | No | Spawned agent nesting depth (root session starts at 0). |261| `agents.max_concurrent_threads_per_session` | number | No | Cap concurrently open spawned-agent threads, excluding the primary. |

267| `agents.job_max_runtime_seconds` | number | No | Default timeout per worker for `spawn_agents_on_csv` jobs. |262| `agents.default_subagent_model` | string | No | Set the default model for spawned agents. |

263| `agents.default_subagent_reasoning_effort` | string | No | Set the default reasoning effort for spawned agents. |

268| `agents.interrupt_message` | boolean | No | Record a model-visible message when an agent turn is interrupted. |264| `agents.interrupt_message` | boolean | No | Record a model-visible message when an agent turn is interrupted. |

269 265 

270**Notes:**266**Notes:**

271 267 

272- `agents.max_threads` defaults to `6` when you leave it unset.268- `agents.enabled` defaults to `true`. Set it to `false` to disable multi-agent tools.

273- `agents.max_depth` defaults to `1`, which lets the root thread spawn direct children but prevents those children from spawning deeper descendants. Keep the default unless you specifically need recursive delegation. Raising this value can turn broad delegation instructions into repeated fan-out, which increases token usage, latency, and local resource consumption. `agents.max_threads` still caps concurrent open threads, but it doesn't remove the cost and predictability risks of deeper recursion.269- When you leave `agents.max_concurrent_threads_per_session` unset, Codex chooses the default. Existing configurations can keep using `agents.max_threads` as a legacy alias.

274- `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.270- Explicit spawn values override `agents.default_subagent_model` and `agents.default_subagent_reasoning_effort`.

275- `agents.interrupt_message` defaults to `true`. Set it to `false` to omit the model-visible interruption message from the agent's context.271- `agents.interrupt_message` defaults to `true`. Set it to `false` to omit the model-visible interruption message from the agent's context.

276- If a custom agent name matches a built-in agent such as `explorer`, your custom agent takes precedence.272- If a custom agent name matches a built-in agent such as `explorer`, your custom agent takes precedence.

277 273 

278### Custom agent file schema274### Custom agent file schema

279 275 

280| Field | Type | Required | Purpose |276| Field | Type | Required | Purpose |

281| ------------------------ | -------- | :------: | --------------------------------------------------------------- |277| ------------------------ | ------ | :------: | --------------------------------------------------------------- |

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

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

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

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

286 281 

287You 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`.282You 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`.

288 283 

290the agent name is the simplest convention, but the `name` field is the source285the agent name is the simplest convention, but the `name` field is the source

291of truth.286of truth.

292 287 

293### Display nicknames

294 

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

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

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

298instead of repeating the same agent name.

299 

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

301its `name`.

302 

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

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

305 

306Example:

307 

308```toml

309name = "reviewer"

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

311developer_instructions = """

312Review code like an owner.

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

314"""

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

316```

317 

318In practice, the ChatGPT desktop app, Codex CLI, and IDE extension can show the

319nicknames where agent activity appears, while the underlying agent type stays

320`reviewer`.

321 

322### Example custom agents288### Example custom agents

323 289 

324The best custom agents are narrow and opinionated. Give each one clear job, a290The best custom agents are narrow and opinionated. Give each one clear job, a

337 303 

338```toml304```toml

339[agents]305[agents]

340max_threads = 6306max_concurrent_threads_per_session = 8

341max_depth = 1

342```307```

343 308 

344`.codex/agents/pr-explorer.toml`:309`.codex/agents/pr-explorer.toml`:

395Review 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.360Review 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.

396```361```

397 362 

398## Process CSV batches with subagents (experimental)

399 

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

401Use `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.

402 

403This works well for repeated audits such as:

404 

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

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

407- generating structured summaries for many similar inputs

408 

409The tool accepts:

410 

411- `csv_path` for the source CSV

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

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

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

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

416 

417Each 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.

418 

419Example prompt:

420 

421```text

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

423 

424Then call spawn_agents_on_csv with:

425- csv_path: /tmp/components.csv

426- id_column: path

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

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

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

430```

431 

432When 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`.

433 

434Related runtime settings:

435 

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

437- `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.

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

439 

440#### Example 2: Frontend integration debugging363#### Example 2: Frontend integration debugging

441 364 

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

445 368 

446```toml369```toml

447[agents]370[agents]

448max_threads = 6371max_concurrent_threads_per_session = 6

449max_depth = 1

450```372```

451 373 

452`.codex/agents/code-mapper.toml`:374`.codex/agents/code-mapper.toml`:

701 701 

702For a detailed walkthrough, see [Custom instructions with AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md).702For a detailed walkthrough, see [Custom instructions with AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md).

703 703 

704## Desktop

705 

706Options in this section apply only to the ChatGPT desktop app.

707 

708### Add custom file handlers

709 

710In your user-level `~/.codex/config.toml`, add entries under

711`desktop.custom_file_handlers` to open files in editors or internal launchers

712that the ChatGPT desktop app doesn't support by default. Each entry adds an

713editor target to the app's **Open in** menus. The app lists the target when

714`command` is an existing absolute path or resolves from the app's `PATH`.

715 

716The following example shows three ways to pass a file to a handler:

717 

718```toml

719# Append the opened path directly after the command.

720[desktop.custom_file_handlers.vscodium]

721label = "VSCodium"

722icon = "/Users/you/.codex/icons/vscodium.png"

723command = "codium"

724 

725# Place fixed arguments before the opened path.

726[desktop.custom_file_handlers.textedit]

727label = "TextEdit"

728icon = "/Users/you/.codex/icons/textedit.png"

729command = "/usr/bin/open"

730args = ["-a", "TextEdit"]

731 

732# Append one JSON argument with the path and editor context.

733[desktop.custom_file_handlers.company_editor]

734label = "Company Editor"

735icon = "/opt/company/editor/icon.png"

736command = "/opt/company/bin/editor"

737input = "json_argument"

738```

739 

740Save `config.toml`, then restart the ChatGPT desktop app.

741 

742The handler ID is the final segment of the TOML table header. It must contain

7431–64 characters, start with an ASCII letter or number, and otherwise contain

744only ASCII letters, numbers, periods, underscores, or hyphens. The app exposes

745the ID with a `custom:` prefix; for example, `company_editor` becomes

746`custom:company_editor`. Quote an ID that contains a period so TOML doesn't

747interpret it as a nested table. For example:

748 

749```toml

750[desktop.custom_file_handlers."company.editor"]

751label = "Company Editor"

752icon = "/opt/company/editor/icon.png"

753command = "/opt/company/bin/editor"

754```

755 

756Each handler supports these fields:

757 

758| Field | Required | Description |

759| -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

760| `label` | Yes | Display name in the app. |

761| `icon` | Yes | Bundled app icon such as `apps/vscode.png`, base64 `data:image/...` URL, `file:` URI, or absolute local image path. An unsupported source uses the default VS Code icon. |

762| `command` | Yes | Executable path or command name to detect and launch. |

763| `args` | No | String array inserted between `command` and the file input. Defaults to `[]`. |

764| `input` | No | How the app sends file input: `path`, `json_argument`, or `json_stdin`. Defaults to `path`. |

765| `supports_ssh` | No | Whether to offer the handler for files in SSH workspaces. Defaults to `false`. Use `json_stdin` when the handler needs remote host and path details. |

766 

767The `input` value controls what follows `args`:

768 

769- `path` appends the path as the final command argument.

770- `json_argument` appends a JSON object with `target`, `path`, `appPath`, and

771 `location`. The `location` value is an object with 1-based `line` and

772 `column` values, or `null`.

773- `json_stdin` writes the JSON object to standard input instead of adding an

774 argument. It also includes `hostConfig`, `remoteWorkspaceRoot`, and

775 `remotePath`; these fields are `null` when they don't apply.

776 

777For example, `company_editor` can receive this argument when the user opens a

778specific source location:

779 

780```json

781{

782 "target": "custom:company_editor",

783 "path": "/repo/src/index.ts",

784 "appPath": null,

785 "location": { "line": 12, "column": 3 }

786}

787```

788 

789Selecting a custom handler as the preferred editor persists the choice the same

790way as selecting a built-in editor, including per-project preferences.

791 

704## TUI options792## TUI options

705 793 

706Running `codex` with no subcommand launches the interactive terminal UI (TUI). Codex exposes some TUI-specific configuration under `[tui]`, including:794Running `codex` with no subcommand launches the interactive terminal UI (TUI). Codex exposes some TUI-specific configuration under `[tui]`, including:

701 701 

702For a detailed walkthrough, see [Custom instructions with AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md).702For a detailed walkthrough, see [Custom instructions with AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md).

703 703 

704## Desktop

705 

706Options in this section apply only to the ChatGPT desktop app.

707 

708### Add custom file handlers

709 

710In your user-level `~/.codex/config.toml`, add entries under

711`desktop.custom_file_handlers` to open files in editors or internal launchers

712that the ChatGPT desktop app doesn't support by default. Each entry adds an

713editor target to the app's **Open in** menus. The app lists the target when

714`command` is an existing absolute path or resolves from the app's `PATH`.

715 

716The following example shows three ways to pass a file to a handler:

717 

718```toml

719# Append the opened path directly after the command.

720[desktop.custom_file_handlers.vscodium]

721label = "VSCodium"

722icon = "/Users/you/.codex/icons/vscodium.png"

723command = "codium"

724 

725# Place fixed arguments before the opened path.

726[desktop.custom_file_handlers.textedit]

727label = "TextEdit"

728icon = "/Users/you/.codex/icons/textedit.png"

729command = "/usr/bin/open"

730args = ["-a", "TextEdit"]

731 

732# Append one JSON argument with the path and editor context.

733[desktop.custom_file_handlers.company_editor]

734label = "Company Editor"

735icon = "/opt/company/editor/icon.png"

736command = "/opt/company/bin/editor"

737input = "json_argument"

738```

739 

740Save `config.toml`, then restart the ChatGPT desktop app.

741 

742The handler ID is the final segment of the TOML table header. It must contain

7431–64 characters, start with an ASCII letter or number, and otherwise contain

744only ASCII letters, numbers, periods, underscores, or hyphens. The app exposes

745the ID with a `custom:` prefix; for example, `company_editor` becomes

746`custom:company_editor`. Quote an ID that contains a period so TOML doesn't

747interpret it as a nested table. For example:

748 

749```toml

750[desktop.custom_file_handlers."company.editor"]

751label = "Company Editor"

752icon = "/opt/company/editor/icon.png"

753command = "/opt/company/bin/editor"

754```

755 

756Each handler supports these fields:

757 

758| Field | Required | Description |

759| -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

760| `label` | Yes | Display name in the app. |

761| `icon` | Yes | Bundled app icon such as `apps/vscode.png`, base64 `data:image/...` URL, `file:` URI, or absolute local image path. An unsupported source uses the default VS Code icon. |

762| `command` | Yes | Executable path or command name to detect and launch. |

763| `args` | No | String array inserted between `command` and the file input. Defaults to `[]`. |

764| `input` | No | How the app sends file input: `path`, `json_argument`, or `json_stdin`. Defaults to `path`. |

765| `supports_ssh` | No | Whether to offer the handler for files in SSH workspaces. Defaults to `false`. Use `json_stdin` when the handler needs remote host and path details. |

766 

767The `input` value controls what follows `args`:

768 

769- `path` appends the path as the final command argument.

770- `json_argument` appends a JSON object with `target`, `path`, `appPath`, and

771 `location`. The `location` value is an object with 1-based `line` and

772 `column` values, or `null`.

773- `json_stdin` writes the JSON object to standard input instead of adding an

774 argument. It also includes `hostConfig`, `remoteWorkspaceRoot`, and

775 `remotePath`; these fields are `null` when they don't apply.

776 

777For example, `company_editor` can receive this argument when the user opens a

778specific source location:

779 

780```json

781{

782 "target": "custom:company_editor",

783 "path": "/repo/src/index.ts",

784 "appPath": null,

785 "location": { "line": 12, "column": 3 }

786}

787```

788 

789Selecting a custom handler as the preferred editor persists the choice the same

790way as selecting a built-in editor, including per-project preferences.

791 

704## TUI options792## TUI options

705 793 

706Running `codex` with no subcommand launches the interactive terminal UI (TUI). Codex exposes some TUI-specific configuration under `[tui]`, including:794Running `codex` with no subcommand launches the interactive terminal UI (TUI). Codex exposes some TUI-specific configuration under `[tui]`, including:

243 key: "service_tier",243 key: "service_tier",

244 type: "string",244 type: "string",

245 description:245 description:

246 "Preferred service tier for new turns. Built-in values include `flex` and `fast`; legacy `fast` config maps to the request value `priority`, and catalog-provided tier IDs can also be stored.",246 "Preferred service tier for new turns. Use `fast` or another tier advertised by the active model; `fast` maps to the request value `priority`.",

247 },247 },

248 {248 {

249 key: "experimental_compact_prompt_file",249 key: "experimental_compact_prompt_file",

569 "Experimental placement for an MCP server. `remote` starts stdio servers through a remote executor environment; streamable HTTP remote placement is not implemented.",569 "Experimental placement for an MCP server. `remote` starts stdio servers through a remote executor environment; streamable HTTP remote placement is not implemented.",

570 },570 },

571 {571 {

572 key: "agents.max_threads",572 key: "agents",

573 type: "number",573 type: "table",

574 description:574 description:

575 "Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset.",575 "Multi-agent settings and custom role declarations. Scalar setting names are reserved and can't be used as custom role names.",

576 },

577 {

578 key: "agents.enabled",

579 type: "boolean",

580 description: "Enable or disable multi-agent tools (default: true).",

576 },581 },

577 {582 {

578 key: "agents.max_depth",583 key: "agents.max_concurrent_threads_per_session",

579 type: "number",584 type: "number",

580 description:585 description:

581 "Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1).",586 "Maximum number of spawned-agent threads that can be open concurrently, excluding the primary thread. When unset, Codex chooses the default.",

582 },587 },

583 {588 {

584 key: "agents.job_max_runtime_seconds",589 key: "agents.max_threads",

585 type: "number",590 type: "number",

586 description:591 description:

587 "Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker.",592 "Legacy alias for `agents.max_concurrent_threads_per_session`.",

593 },

594 {

595 key: "agents.default_subagent_model",

596 type: "string",

597 description:

598 "Default model for spawned agents. An explicit spawn model takes precedence.",

599 },

600 {

601 key: "agents.default_subagent_reasoning_effort",

602 type: "string",

603 description:

604 "Default reasoning effort for spawned agents. An explicit spawn effort takes precedence.",

588 },605 },

589 {606 {

590 key: "agents.interrupt_message",607 key: "agents.interrupt_message",

604 description:621 description:

605 "Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role.",622 "Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role.",

606 },623 },

607 {

608 key: "agents.<name>.nickname_candidates",

609 type: "array<string>",

610 description:

611 "Optional pool of display nicknames for spawned agents in that role.",

612 },

613 {624 {

614 key: "memories.generate_memories",625 key: "memories.generate_memories",

615 type: "boolean",626 type: "boolean",

1161 type: "string",1172 type: "string",

1162 description: "Client private key path for OTEL trace exporter TLS.",1173 description: "Client private key path for OTEL trace exporter TLS.",

1163 },1174 },

1175 {

1176 key: "desktop.custom_file_handlers.<id>",

1177 type: "table",

1178 description:

1179 "User-level only. Defines an additional **Open in** target for the ChatGPT desktop app. See [Add custom file handlers](https://learn.chatgpt.com/docs/config-file/config-advanced#add-custom-file-handlers) for examples and handler ID constraints.",

1180 },

1181 {

1182 key: "desktop.custom_file_handlers.<id>.label",

1183 type: "string",

1184 description: "Display name shown in **Open in** menus. Required.",

1185 },

1186 {

1187 key: "desktop.custom_file_handlers.<id>.icon",

1188 type: "string",

1189 description:

1190 "Bundled asset path, Base64-encoded `data:image/...` URL, file URI, or absolute local path for the handler icon. Required; unsupported sources use the default VS Code icon.",

1191 },

1192 {

1193 key: "desktop.custom_file_handlers.<id>.command",

1194 type: "string",

1195 description:

1196 "Executable path or command name to detect and launch. Required.",

1197 },

1198 {

1199 key: "desktop.custom_file_handlers.<id>.args",

1200 type: "array<string>",

1201 description:

1202 "Arguments inserted between the command and file input (default: `[]`).",

1203 },

1204 {

1205 key: "desktop.custom_file_handlers.<id>.input",

1206 type: "path | json_argument | json_stdin",

1207 description:

1208 "How the app sends file input to the handler (default: `path`).",

1209 },

1210 {

1211 key: "desktop.custom_file_handlers.<id>.supports_ssh",

1212 type: "boolean",

1213 description:

1214 "Offer the handler for files in SSH workspaces (default: `false`).",

1215 },

1164 {1216 {

1165 key: "tui",1217 key: "tui",

1166 type: "table",1218 type: "table",

49 49 

50# oss_provider = "ollama"50# oss_provider = "ollama"

51 51 

52# Preferred service tier. Built-in examples: fast | flex; model catalogs can add more.52# Preferred service tier. Use fast or another tier supported by the active model.

53 53 

54# service_tier = "flex"54# service_tier = "fast"

55 55 

56# Optional manual model metadata. When unset, Codex uses model or preset defaults.56# Optional manual model metadata. When unset, Codex uses model or preset defaults.

57 57 

325 325 

326[agents]326[agents]

327 327 

328# Maximum concurrently open agent threads. Default: 6328# Enable or disable multi-agent tools. Default: true

329 329 

330# max_threads = 6330# enabled = true

331 

332# Maximum concurrently open spawned-agent threads, excluding the primary thread. When unset, Codex chooses the default.

331 333 

332# Maximum nested spawn depth. Root session starts at depth 0. Default: 1334# max_concurrent_threads_per_session = 6

333 335 

334# max_depth = 1336# Default model for spawned agents. An explicit spawn model takes precedence.

335 337 

336# Default timeout per worker for spawn_agents_on_csv jobs. When unset, the tool defaults to 1800 seconds.338# default_subagent_model = "gpt-5.6-terra"

337 339 

338# job_max_runtime_seconds = 1800340# Default reasoning effort for spawned agents. An explicit spawn effort takes precedence.

341 

342# default_subagent_reasoning_effort = "high"

339 343 

340# Record a model-visible message when an agent turn is interrupted. Default: true344# Record a model-visible message when an agent turn is interrupted. Default: true

341 345 

347 351 

348# config_file = "./agents/reviewer.toml" # relative to the config.toml that defines it352# config_file = "./agents/reviewer.toml" # relative to the config.toml that defines it

349 353 

350# nickname_candidates = ["Athena", "Ada"]

351 

352################################################################################354################################################################################

353 355 

354# Skills (per-skill overrides)356# Skills (per-skill overrides)

1013 1015 

1014# sandbox_mode = "read-only"1016# sandbox_mode = "read-only"

1015 1017 

1016# service_tier = "flex" # or another supported service tier id1018# service_tier = "fast" # or another supported service tier id

1017 1019 

1018# oss_provider = "ollama"1020# oss_provider = "ollama"

1019 1021 

243 key: "service_tier",243 key: "service_tier",

244 type: "string",244 type: "string",

245 description:245 description:

246 "Preferred service tier for new turns. Built-in values include `flex` and `fast`; legacy `fast` config maps to the request value `priority`, and catalog-provided tier IDs can also be stored.",246 "Preferred service tier for new turns. Use `fast` or another tier advertised by the active model; `fast` maps to the request value `priority`.",

247 },247 },

248 {248 {

249 key: "experimental_compact_prompt_file",249 key: "experimental_compact_prompt_file",

569 "Experimental placement for an MCP server. `remote` starts stdio servers through a remote executor environment; streamable HTTP remote placement is not implemented.",569 "Experimental placement for an MCP server. `remote` starts stdio servers through a remote executor environment; streamable HTTP remote placement is not implemented.",

570 },570 },

571 {571 {

572 key: "agents.max_threads",572 key: "agents",

573 type: "number",573 type: "table",

574 description:574 description:

575 "Maximum number of agent threads that can be open concurrently. Defaults to `6` when unset.",575 "Multi-agent settings and custom role declarations. Scalar setting names are reserved and can't be used as custom role names.",

576 },

577 {

578 key: "agents.enabled",

579 type: "boolean",

580 description: "Enable or disable multi-agent tools (default: true).",

576 },581 },

577 {582 {

578 key: "agents.max_depth",583 key: "agents.max_concurrent_threads_per_session",

579 type: "number",584 type: "number",

580 description:585 description:

581 "Maximum nesting depth allowed for spawned agent threads (root sessions start at depth 0; default: 1).",586 "Maximum number of spawned-agent threads that can be open concurrently, excluding the primary thread. When unset, Codex chooses the default.",

582 },587 },

583 {588 {

584 key: "agents.job_max_runtime_seconds",589 key: "agents.max_threads",

585 type: "number",590 type: "number",

586 description:591 description:

587 "Default per-worker timeout for `spawn_agents_on_csv` jobs. When unset, the tool falls back to 1800 seconds per worker.",592 "Legacy alias for `agents.max_concurrent_threads_per_session`.",

593 },

594 {

595 key: "agents.default_subagent_model",

596 type: "string",

597 description:

598 "Default model for spawned agents. An explicit spawn model takes precedence.",

599 },

600 {

601 key: "agents.default_subagent_reasoning_effort",

602 type: "string",

603 description:

604 "Default reasoning effort for spawned agents. An explicit spawn effort takes precedence.",

588 },605 },

589 {606 {

590 key: "agents.interrupt_message",607 key: "agents.interrupt_message",

604 description:621 description:

605 "Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role.",622 "Path to a TOML config layer for that role; relative paths resolve from the config file that declares the role.",

606 },623 },

607 {

608 key: "agents.<name>.nickname_candidates",

609 type: "array<string>",

610 description:

611 "Optional pool of display nicknames for spawned agents in that role.",

612 },

613 {624 {

614 key: "memories.generate_memories",625 key: "memories.generate_memories",

615 type: "boolean",626 type: "boolean",

1161 type: "string",1172 type: "string",

1162 description: "Client private key path for OTEL trace exporter TLS.",1173 description: "Client private key path for OTEL trace exporter TLS.",

1163 },1174 },

1175 {

1176 key: "desktop.custom_file_handlers.<id>",

1177 type: "table",

1178 description:

1179 "User-level only. Defines an additional **Open in** target for the ChatGPT desktop app. See [Add custom file handlers](https://learn.chatgpt.com/docs/config-file/config-advanced#add-custom-file-handlers) for examples and handler ID constraints.",

1180 },

1181 {

1182 key: "desktop.custom_file_handlers.<id>.label",

1183 type: "string",

1184 description: "Display name shown in **Open in** menus. Required.",

1185 },

1186 {

1187 key: "desktop.custom_file_handlers.<id>.icon",

1188 type: "string",

1189 description:

1190 "Bundled asset path, Base64-encoded `data:image/...` URL, file URI, or absolute local path for the handler icon. Required; unsupported sources use the default VS Code icon.",

1191 },

1192 {

1193 key: "desktop.custom_file_handlers.<id>.command",

1194 type: "string",

1195 description:

1196 "Executable path or command name to detect and launch. Required.",

1197 },

1198 {

1199 key: "desktop.custom_file_handlers.<id>.args",

1200 type: "array<string>",

1201 description:

1202 "Arguments inserted between the command and file input (default: `[]`).",

1203 },

1204 {

1205 key: "desktop.custom_file_handlers.<id>.input",

1206 type: "path | json_argument | json_stdin",

1207 description:

1208 "How the app sends file input to the handler (default: `path`).",

1209 },

1210 {

1211 key: "desktop.custom_file_handlers.<id>.supports_ssh",

1212 type: "boolean",

1213 description:

1214 "Offer the handler for files in SSH workspaces (default: `false`).",

1215 },

1164 {1216 {

1165 key: "tui",1217 key: "tui",

1166 type: "table",1218 type: "table",

49 49 

50# oss_provider = "ollama"50# oss_provider = "ollama"

51 51 

52# Preferred service tier. Built-in examples: fast | flex; model catalogs can add more.52# Preferred service tier. Use fast or another tier supported by the active model.

53 53 

54# service_tier = "flex"54# service_tier = "fast"

55 55 

56# Optional manual model metadata. When unset, Codex uses model or preset defaults.56# Optional manual model metadata. When unset, Codex uses model or preset defaults.

57 57 

325 325 

326[agents]326[agents]

327 327 

328# Maximum concurrently open agent threads. Default: 6328# Enable or disable multi-agent tools. Default: true

329 329 

330# max_threads = 6330# enabled = true

331 

332# Maximum concurrently open spawned-agent threads, excluding the primary thread. When unset, Codex chooses the default.

331 333 

332# Maximum nested spawn depth. Root session starts at depth 0. Default: 1334# max_concurrent_threads_per_session = 6

333 335 

334# max_depth = 1336# Default model for spawned agents. An explicit spawn model takes precedence.

335 337 

336# Default timeout per worker for spawn_agents_on_csv jobs. When unset, the tool defaults to 1800 seconds.338# default_subagent_model = "gpt-5.6-terra"

337 339 

338# job_max_runtime_seconds = 1800340# Default reasoning effort for spawned agents. An explicit spawn effort takes precedence.

341 

342# default_subagent_reasoning_effort = "high"

339 343 

340# Record a model-visible message when an agent turn is interrupted. Default: true344# Record a model-visible message when an agent turn is interrupted. Default: true

341 345 

347 351 

348# config_file = "./agents/reviewer.toml" # relative to the config.toml that defines it352# config_file = "./agents/reviewer.toml" # relative to the config.toml that defines it

349 353 

350# nickname_candidates = ["Athena", "Ada"]

351 

352################################################################################354################################################################################

353 355 

354# Skills (per-skill overrides)356# Skills (per-skill overrides)

1013 1015 

1014# sandbox_mode = "read-only"1016# sandbox_mode = "read-only"

1015 1017 

1016# service_tier = "flex" # or another supported service tier id1018# service_tier = "fast" # or another supported service tier id

1017 1019 

1018# oss_provider = "ollama"1020# oss_provider = "ollama"

1019 1021 

119Skills can be global (in your user directory, for you as a developer) or repo-specific (checked into `.agents/skills`, for your team). Put repo skills in `.agents/skills` when the workflow applies to that project; use your user directory for skills you want across all repos.119Skills can be global (in your user directory, for you as a developer) or repo-specific (checked into `.agents/skills`, for your team). Put repo skills in `.agents/skills` when the workflow applies to that project; use your user directory for skills you want across all repos.

120 120 

121| Layer | Global | Repo |121| Layer | Global | Repo |

122| :----- | :--------------------- | :--------------------------------------------- |122| :----- | :------------------- | :--------------------------------------------- |

123| AGENTS | `~/.codex/AGENTS.md` | `AGENTS.md` in repo root or nested directories |123| AGENTS | `~/.codex/AGENTS.md` | `AGENTS.md` in repo root or nested directories |

124| Skills | `$HOME/.agents/skills` | `.agents/skills` in repo |124| Skills | `~/.agents/skills` | `.agents/skills` in repo |

125 125 

126Codex uses progressive disclosure for skills:126Codex uses progressive disclosure for skills:

127 127 

114For most tasks in Codex, start with 114For most tasks in Codex, start with

115 `gpt-5.6`. Use 115 `gpt-5.6`. Use

116 `gpt-5.6-terra` when you want116 `gpt-5.6-terra` when you want

117 a faster, lower-cost option for lighter subagent work. If you have ChatGPT Pro117 a faster, lower-cost option for lighter subagent work.

118 and want near-instant text-only iteration, `gpt-5.3-codex-spark` remains

119 available in research preview.

120 118 

121### Model choice119### Model choice

122 120 

123- **`gpt-5.6`**: Start here for demanding agents. It's strongest for ambiguous, multi-step work that needs planning, tool use, validation, and follow-through across a larger context.121- **`gpt-5.6`**: Start here for demanding agents. It's strongest for ambiguous, multi-step work that needs planning, tool use, validation, and follow-through across a larger context.

124- **`gpt-5.4`**: Use this when a workflow is pinned to GPT-5.4. It combines strong coding, reasoning, tool use, and broader workflows.122- **`gpt-5.4`**: Use this when a workflow is pinned to GPT-5.4. It combines strong coding, reasoning, tool use, and broader workflows.

125- **`gpt-5.6-terra`**: Use for agents that favor speed and efficiency over depth, such as exploration, read-heavy scans, large-file review, or processing supporting documents. It works well for parallel workers that return distilled results to the main agent.123- **`gpt-5.6-terra`**: Use for agents that favor speed and efficiency over depth, such as exploration, read-heavy scans, large-file review, or processing supporting documents. It works well for parallel workers that return distilled results to the main agent.

126- **`gpt-5.3-codex-spark`**: If you have ChatGPT Pro, use this research preview model for near-instant, text-only iteration when latency matters more than broader capability.

127 124 

128### Reasoning effort (`model_reasoning_effort`)125### Reasoning effort (`model_reasoning_effort`)

129 126 

134- **`high`**: Use when an agent needs to trace complex logic, check assumptions, or work through edge cases (for example, reviewer or security-focused agents).131- **`high`**: Use when an agent needs to trace complex logic, check assumptions, or work through edge cases (for example, reviewer or security-focused agents).

135- **`medium`**: A balanced default for most agents.132- **`medium`**: A balanced default for most agents.

136- **`low`**: Use when the task is straightforward and speed matters most.133- **`low`**: Use when the task is straightforward and speed matters most.

137- **`minimal`** and **`none`**: Use when the selected model supports these

138 lower-latency levels and the task needs little or no reasoning.

139 134 

140Higher reasoning effort increases response time and token usage, but it can improve quality for complex work. For details, see [Models](https://learn.chatgpt.com/docs/models), [Config basics](https://learn.chatgpt.com/docs/config-file/config-basic), and [Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-reference).135Higher reasoning effort increases response time and token usage, but it can improve quality for complex work. For details, see [Models](https://learn.chatgpt.com/docs/models), [Config basics](https://learn.chatgpt.com/docs/config-file/config-basic), and [Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-reference).

141 136 

142<code>agents.max_depth</code> controls nesting and defaults to <code>1</code>,

143 which lets the root thread spawn direct children but prevents those children

144 from spawning deeper descendants.

145 

146 137 

147 138 

148## Orchestration and thread controls139## Orchestration and thread controls

252- `description`243- `description`

253- `developer_instructions`244- `developer_instructions`

254 245 

255Optional fields such as `nickname_candidates`, `model`,246If a custom agent file sets `model` or `model_reasoning_effort`, the value in

256`model_reasoning_effort`, `sandbox_mode`, `mcp_servers`, and `skills.config`247the file takes precedence. Otherwise, Codex resolves each setting independently:

257inherit from the parent session when you omit them.248an explicit spawn value, then the corresponding `[agents]` default, then the

249parent's value. If a spawn selects a different model and neither an explicit nor

250configured effort is present, Codex uses that model's default effort. Other

251session settings, such as `sandbox_mode`, `mcp_servers`, and `skills.config`,

252inherit from the parent when the custom agent file omits them.

258 253 

259### Global settings254### Global settings

260 255 

261Global subagent settings still live under `[agents]` in your [configuration](https://learn.chatgpt.com/docs/config-file/config-basic#configuration-precedence).256Global subagent settings still live under `[agents]` in your [configuration](https://learn.chatgpt.com/docs/config-file/config-basic#configuration-precedence).

262 257 

263| Field | Type | Required | Purpose |258| Field | Type | Required | Purpose |

264| -------------------------------- | ------- | :------: | ----------------------------------------------------------------- |259| ------------------------------------------- | ------- | :------: | ------------------------------------------------------------------- |

265| `agents.max_threads` | number | No | Concurrent open agent thread cap. |260| `agents.enabled` | boolean | No | Enable or disable multi-agent tools. |

266| `agents.max_depth` | number | No | Spawned agent nesting depth (root session starts at 0). |261| `agents.max_concurrent_threads_per_session` | number | No | Cap concurrently open spawned-agent threads, excluding the primary. |

267| `agents.job_max_runtime_seconds` | number | No | Default timeout per worker for `spawn_agents_on_csv` jobs. |262| `agents.default_subagent_model` | string | No | Set the default model for spawned agents. |

263| `agents.default_subagent_reasoning_effort` | string | No | Set the default reasoning effort for spawned agents. |

268| `agents.interrupt_message` | boolean | No | Record a model-visible message when an agent turn is interrupted. |264| `agents.interrupt_message` | boolean | No | Record a model-visible message when an agent turn is interrupted. |

269 265 

270**Notes:**266**Notes:**

271 267 

272- `agents.max_threads` defaults to `6` when you leave it unset.268- `agents.enabled` defaults to `true`. Set it to `false` to disable multi-agent tools.

273- `agents.max_depth` defaults to `1`, which lets the root thread spawn direct children but prevents those children from spawning deeper descendants. Keep the default unless you specifically need recursive delegation. Raising this value can turn broad delegation instructions into repeated fan-out, which increases token usage, latency, and local resource consumption. `agents.max_threads` still caps concurrent open threads, but it doesn't remove the cost and predictability risks of deeper recursion.269- When you leave `agents.max_concurrent_threads_per_session` unset, Codex chooses the default. Existing configurations can keep using `agents.max_threads` as a legacy alias.

274- `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.270- Explicit spawn values override `agents.default_subagent_model` and `agents.default_subagent_reasoning_effort`.

275- `agents.interrupt_message` defaults to `true`. Set it to `false` to omit the model-visible interruption message from the agent's context.271- `agents.interrupt_message` defaults to `true`. Set it to `false` to omit the model-visible interruption message from the agent's context.

276- If a custom agent name matches a built-in agent such as `explorer`, your custom agent takes precedence.272- If a custom agent name matches a built-in agent such as `explorer`, your custom agent takes precedence.

277 273 

278### Custom agent file schema274### Custom agent file schema

279 275 

280| Field | Type | Required | Purpose |276| Field | Type | Required | Purpose |

281| ------------------------ | -------- | :------: | --------------------------------------------------------------- |277| ------------------------ | ------ | :------: | --------------------------------------------------------------- |

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

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

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

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

286 281 

287You 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`.282You 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`.

288 283 

290the agent name is the simplest convention, but the `name` field is the source285the agent name is the simplest convention, but the `name` field is the source

291of truth.286of truth.

292 287 

293### Display nicknames

294 

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

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

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

298instead of repeating the same agent name.

299 

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

301its `name`.

302 

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

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

305 

306Example:

307 

308```toml

309name = "reviewer"

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

311developer_instructions = """

312Review code like an owner.

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

314"""

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

316```

317 

318In practice, the ChatGPT desktop app, Codex CLI, and IDE extension can show the

319nicknames where agent activity appears, while the underlying agent type stays

320`reviewer`.

321 

322### Example custom agents288### Example custom agents

323 289 

324The best custom agents are narrow and opinionated. Give each one clear job, a290The best custom agents are narrow and opinionated. Give each one clear job, a

337 303 

338```toml304```toml

339[agents]305[agents]

340max_threads = 6306max_concurrent_threads_per_session = 8

341max_depth = 1

342```307```

343 308 

344`.codex/agents/pr-explorer.toml`:309`.codex/agents/pr-explorer.toml`:

395Review 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.360Review 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.

396```361```

397 362 

398## Process CSV batches with subagents (experimental)

399 

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

401Use `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.

402 

403This works well for repeated audits such as:

404 

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

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

407- generating structured summaries for many similar inputs

408 

409The tool accepts:

410 

411- `csv_path` for the source CSV

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

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

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

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

416 

417Each 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.

418 

419Example prompt:

420 

421```text

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

423 

424Then call spawn_agents_on_csv with:

425- csv_path: /tmp/components.csv

426- id_column: path

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

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

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

430```

431 

432When 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`.

433 

434Related runtime settings:

435 

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

437- `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.

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

439 

440#### Example 2: Frontend integration debugging363#### Example 2: Frontend integration debugging

441 364 

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

445 368 

446```toml369```toml

447[agents]370[agents]

448max_threads = 6371max_concurrent_threads_per_session = 6

449max_depth = 1

450```372```

451 373 

452`.codex/agents/code-mapper.toml`:374`.codex/agents/code-mapper.toml`: