Subagents

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.

With subagent workflows, you can also define your own custom agents with different model configurations and instructions depending on the task.

For the concepts and tradeoffs behind subagent workflows, including context pollution, context rot, and model-selection guidance, see Subagent concepts.

Availability

Current Codex releases enable subagent workflows by default.

Codex only spawns subagents when you explicitly ask it to. Because each subagent does its own model and tool work, subagent workflows consume more tokens than comparable single-agent runs.

Typical workflow

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.

Codex only spawns a new agent when you explicitly ask it to do so.

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

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

• Use /agent in the CLI to switch between active agent threads and inspect the ongoing thread.
• Ask Codex directly to steer a running subagent, stop it, or close completed agent threads.

Approvals and sandbox controls

Subagents inherit your current sandbox policy.

In interactive CLI sessions, approval requests can surface from inactive agent threads even while you are looking at the main thread. The approval overlay shows the source thread label, and you can press o to open that thread before you approve, reject, or answer the request.

In non-interactive flows, or whenever a run can’t surface a fresh approval, an action that needs new approval fails and Codex surfaces the error back to the parent workflow.

Codex also reapplies the parent turn’s live runtime overrides when it spawns a child. That includes sandbox and approval choices you set interactively during the session, such as /approvals changes or --yolo, even if the selected custom agent file sets different defaults.

You can also override the sandbox configuration for individual 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.

Notes:

• agents.max_threads defaults to 6 when you leave it unset.
• agents.max_depth defaults to 1, which allows a direct child agent to spawn but prevents deeper nesting.
• 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.
• If a custom agent name matches a built-in agent such as explorer, your custom agent takes precedence.

Custom agent file schema

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:

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 Codex app and CLI 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):

[agents]
max_threads = 6
max_depth = 1

.codex/agents/pr-explorer.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:

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:

name = "docs_researcher"
description = "Documentation specialist that uses the docs MCP server to verify APIs and framework behavior."
model = "gpt-5.3-codex-spark"
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:

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:

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):

[agents]
max_threads = 6
max_depth = 1

.codex/agents/code-mapper.toml:

name = "code_mapper"
description = "Read-only codebase explorer for locating the relevant frontend and backend code paths."
model = "gpt-5.3-codex-spark"
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:

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:

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:

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.