# Subagents
Work mode and Codex 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.
In local Codex clients, you can also define custom agents with different model
configurations and instructions for different tasks.
## Availability
Current Codex releases enable subagent workflows by default. Subagent activity
appears in the ChatGPT desktop app, Codex CLI, and the IDE extension.
Because each subagent does its own model and tool work, subagent workflows
consume more tokens than comparable single-agent runs.
Ask Codex in an app chat to delegate independent parts of the work to
subagents. Current local Codex releases delegate when you ask directly or when
applicable `AGENTS.md` or skill instructions request it. The app surfaces each
subagent thread so you can inspect its work and the summary returned to the main
chat.
## Why subagent workflows help
Even with large context windows, models have limits. If you flood the main chat (where you're defining requirements, constraints, and decisions) with noisy intermediate output such as exploration notes, test logs, stack traces, and command output, the session can become less reliable over time.
This is often described as:
- **Context pollution**: useful information gets buried under noisy intermediate output.
- **Context rot**: performance degrades as the chat fills up with less relevant details.
For background, see the Chroma writeup on [context rot](https://research.trychroma.com/context-rot).
Subagent workflows help by moving noisy work off the main thread:
- Keep the **main agent** focused on requirements, decisions, and final outputs.
- Run specialized **subagents** in parallel for exploration, tests, or log analysis.
- Return **summaries** from subagents instead of raw intermediate output.
They can also save time when the work can run independently in parallel, and
they make larger-shaped tasks more tractable by breaking them into bounded
pieces. For example, Codex can split analysis of a multi-million-token
document into smaller problems and return distilled takeaways to the main
thread.
As a starting point, use parallel agents for read-heavy tasks such as
exploration, tests, triage, and summarization. Be more careful with parallel
write-heavy workflows, because agents editing code at once can create
conflicts and increase coordination overhead.
## Core terms
Codex uses a few related terms in subagent workflows:
- **Subagent workflow**: A workflow where Codex runs parallel agents and combines their results.
- **Subagent**: A delegated agent that Codex starts to handle a specific task.
- **Agent thread**: The thread where a subagent does its work. Supported clients let you open these threads to inspect progress or results.
## Triggering subagent workflows
Ask for subagents or parallel agent work directly. Codex can also delegate when
applicable project or skill instructions request it.
In practice, manual triggering means using direct instructions such as
"spawn two agents," "delegate this work in parallel," or "use one agent per
point." Subagent workflows consume more tokens than comparable single-agent runs
because each subagent does its own model and tool work.
A good subagent prompt should explain how to divide the work, whether Codex
should wait for all agents before continuing, and what summary or output to
return.
```text
Review this branch with parallel subagents. Spawn one subagent for security risks, one for test gaps, and one for maintainability. Wait for all three, then summarize the findings by category with file references.
```
## Choosing models and reasoning
Different agents need different model and reasoning settings.
If you don't pin a model or `model_reasoning_effort`, Codex can choose a setup
that balances intelligence, speed, and price for the task. It may favor `gpt-5.6-terra` for fast scans or a higher-effort `gpt-5.6` configuration for more demanding reasoning. When you want finer control, steer that choice in your prompt or set `model` and `model_reasoning_effort` directly in the agent file.
For most tasks in Codex, start with
`gpt-5.6`. Use
`gpt-5.6-terra` when you want
a faster, lower-cost option for lighter subagent work. If you have ChatGPT Pro
and want near-instant text-only iteration, `gpt-5.3-codex-spark` remains
available in research preview.
### Model choice
- **`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.
- **`gpt-5.4`**: Use this when a workflow is pinned to GPT-5.4. It combines strong coding, reasoning, tool use, and broader workflows.
- **`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.
- **`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.
### Reasoning effort (`model_reasoning_effort`)
- **`ultra`**: Use for the deepest reasoning when the selected model supports
it.
- **`max`** and **`xhigh`**: Use for especially demanding reasoning when the
selected model supports these levels.
- **`high`**: Use when an agent needs to trace complex logic, check assumptions, or work through edge cases (for example, reviewer or security-focused agents).
- **`medium`**: A balanced default for most agents.
- **`low`**: Use when the task is straightforward and speed matters most.
- **`minimal`** and **`none`**: Use when the selected model supports these
lower-latency levels and the task needs little or no reasoning.
Higher 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).
agents.max_depth controls nesting and defaults to 1,
which lets the root thread spawn direct children but prevents those children
from spawning deeper descendants.
## Orchestration and thread controls
ChatGPT or Codex handles orchestration across agents, including spawning new
subagents, routing follow-up instructions, waiting for results, and closing
agent threads.
When many agents are running, Codex waits until all requested results are
available, then returns a consolidated response.
Current local Codex releases spawn agents after a direct request or applicable
project or skill instruction.
To see it in action, try the following prompt on your project:
```text
I 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.
1. Security issue
2. Code quality
3. Bugs
4. Race
5. Test flakiness
6. Maintainability of the code
```
## Managing subagents
- Open a subagent thread from the activity shown in the main thread to inspect
its work.
- Ask Codex directly to steer a running subagent, stop it, or close completed
subagent threads.
## Approvals and sandbox controls
Subagents inherit your current sandbox policy.
Subagents inherit the permission mode selected beneath the composer. Choose the
permission mode for the parent turn before you ask Codex to delegate work.
You can also override the sandbox configuration for individual [custom agents](#custom-agents), such as explicitly marking one to work in read-only mode.
## Custom agents
Codex ships with built-in agents:
- `default`: general-purpose fallback agent.
- `worker`: execution-focused agent for implementation and fixes.
- `explorer`: read-heavy codebase exploration agent.
To define your own custom agents, add standalone TOML files under
`~/.codex/agents/` for personal agents or `.codex/agents/` for project-scoped
agents.
Each file defines one custom agent. Codex loads these files as configuration
layers for spawned sessions, so custom agents can override the same settings as
a normal Codex session config. That can feel heavier than a dedicated agent
manifest, and the format may evolve as authoring and sharing mature.
Every standalone custom agent file must define:
- `name`
- `description`
- `developer_instructions`
Optional fields such as `nickname_candidates`, `model`,
`model_reasoning_effort`, `sandbox_mode`, `mcp_servers`, and `skills.config`
inherit from the parent session when you omit them.
### Global settings
Global subagent settings still live under `[agents]` in your [configuration](https://learn.chatgpt.com/docs/config-file/config-basic#configuration-precedence).
| Field | Type | Required | Purpose |
| -------------------------------- | ------- | :------: | ----------------------------------------------------------------- |
| `agents.max_threads` | number | No | Concurrent open agent thread cap. |
| `agents.max_depth` | number | No | Spawned agent nesting depth (root session starts at 0). |
| `agents.job_max_runtime_seconds` | number | No | Default timeout per worker for `spawn_agents_on_csv` jobs. |
| `agents.interrupt_message` | boolean | No | Record a model-visible message when an agent turn is interrupted. |
**Notes:**
- `agents.max_threads` defaults to `6` when you leave it unset.
- `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.
- `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.
- `agents.interrupt_message` defaults to `true`. Set it to `false` to omit the model-visible interruption message from the agent's context.
- If a custom agent name matches a built-in agent such as `explorer`, your custom agent takes precedence.
### Custom agent file schema
| Field | Type | Required | Purpose |
| ------------------------ | -------- | :------: | --------------------------------------------------------------- |
| `name` | string | Yes | Agent name Codex uses when spawning or referring to this agent. |
| `description` | string | Yes | Human-facing guidance for when Codex should use this agent. |
| `developer_instructions` | string | Yes | Core instructions that define the agent's behavior. |
| `nickname_candidates` | string[] | No | Optional pool of display nicknames for spawned agents. |
You 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`.
Codex identifies the custom agent by its `name` field. Matching the filename to
the agent name is the simplest convention, but the `name` field is the source
of truth.
### Display nicknames
Use `nickname_candidates` when you want Codex to assign more readable display
names to spawned agents. This is especially helpful when you run many
instances of the same custom agent and want the UI to show distinct labels
instead of repeating the same agent name.
Nicknames are presentation-only. Codex still identifies and spawns the agent by
its `name`.
Nickname candidates must be a non-empty list of unique names. Each nickname can
use ASCII letters, digits, spaces, hyphens, and underscores.
Example:
```toml
name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
developer_instructions = """
Review code like an owner.
Prioritize correctness, security, behavior regressions, and missing test coverage.
"""
nickname_candidates = ["Atlas", "Delta", "Echo"]
```
In practice, the ChatGPT desktop app, Codex CLI, and IDE extension can show the
nicknames where agent activity appears, while the underlying agent type stays
`reviewer`.
### Example custom agents
The best custom agents are narrow and opinionated. Give each one clear job, a
tool surface that matches that job, and instructions that keep it from
drifting into adjacent work.
#### Example 1: PR review
This pattern splits review across three focused custom agents:
- `pr_explorer` maps the codebase and gathers evidence.
- `reviewer` looks for correctness, security, and test risks.
- `docs_researcher` checks framework or API documentation through a dedicated MCP server.
Project config (`.codex/config.toml`):
```toml
[agents]
max_threads = 6
max_depth = 1
```
`.codex/agents/pr-explorer.toml`:
```toml
name = "pr_explorer"
description = "Read-only codebase explorer for gathering evidence before changes are proposed."
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Stay in exploration mode.
Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks for them.
Prefer fast search and targeted file reads over broad scans.
"""
```
`.codex/agents/reviewer.toml`:
```toml
name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
Review code like an owner.
Prioritize correctness, security, behavior regressions, and missing test coverage.
Lead with concrete findings, include reproduction steps when possible, and avoid style-only comments unless they hide a real bug.
"""
```
`.codex/agents/docs-researcher.toml`:
```toml
name = "docs_researcher"
description = "Documentation specialist that uses the docs MCP server to verify APIs and framework behavior."
model = "gpt-5.4-mini"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Use the docs MCP server to confirm APIs, options, and version-specific behavior.
Return concise answers with links or exact references when available.
Do not make code changes.
"""
[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"
```
This setup works well for prompts like:
```text
Review 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.
```
## Process CSV batches with subagents (experimental)
This workflow is experimental and may change as subagent support evolves.
Use `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.
This works well for repeated audits such as:
- reviewing one file, package, or service per row
- checking a list of incidents, PRs, or migration targets
- generating structured summaries for many similar inputs
The tool accepts:
- `csv_path` for the source CSV
- `instruction` for the worker prompt template, using `{column_name}` placeholders
- `id_column` when you want stable item ids from a specific column
- `output_schema` when each worker should return a JSON object with a fixed shape
- `output_csv_path`, `max_concurrency`, and `max_runtime_seconds` for job control
Each 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.
Example prompt:
```text
Create /tmp/components.csv with columns path,owner and one row per frontend component.
Then call spawn_agents_on_csv with:
- csv_path: /tmp/components.csv
- id_column: path
- instruction: "Review {path} owned by {owner}. Return JSON with keys path, risk, summary, and follow_up via report_agent_job_result."
- output_csv_path: /tmp/components-review.csv
- output_schema: an object with required string fields path, risk, summary, and follow_up
```
When 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`.
Related runtime settings:
- `agents.max_threads` caps how many agent threads can stay open concurrently.
- `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.
- `sqlite_home` controls where Codex stores the SQLite-backed state used for agent jobs and their exported results.
#### Example 2: Frontend integration debugging
This pattern is useful for UI regressions, flaky browser flows, or integration bugs that cross application code and the running product.
Project config (`.codex/config.toml`):
```toml
[agents]
max_threads = 6
max_depth = 1
```
`.codex/agents/code-mapper.toml`:
```toml
name = "code_mapper"
description = "Read-only codebase explorer for locating the relevant frontend and backend code paths."
model = "gpt-5.4-mini"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Map the code that owns the failing UI flow.
Identify entry points, state transitions, and likely files before the worker starts editing.
"""
```
`.codex/agents/browser-debugger.toml`:
```toml
name = "browser_debugger"
description = "UI debugger that uses browser tooling to reproduce issues and capture evidence."
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"
developer_instructions = """
Reproduce the issue in the browser, capture exact steps, and report what the UI actually does.
Use browser tooling for screenshots, console output, and network evidence.
Do not edit application code.
"""
[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
startup_timeout_sec = 20
```
`.codex/agents/ui-fixer.toml`:
```toml
name = "ui_fixer"
description = "Implementation-focused agent for small, targeted fixes after the issue is understood."
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "medium"
developer_instructions = """
Own the fix once the issue is reproduced.
Make the smallest defensible change, keep unrelated files untouched, and validate only the behavior you changed.
"""
[[skills.config]]
path = "/Users/me/.agents/skills/docs-editor/SKILL.md"
enabled = false
```
This setup works well for prompts like:
```text
Investigate 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.
```