# Subagents in Codex

Codex starts subagents in their own threads, either from built-in roles or from TOML custom agents in .codex/agents/, and they inherit your sandbox and approval setup.

Source: https://ai-sw-factory.mellicci.dev/fundamentals/subagents/codex

This page covers Codex CLI. The desktop app and the IDE extension use the same agent files and show subagent threads in their own UI.

## At a glance

| | Codex |
|---|---|
| Term | Subagents; saved ones are custom agents |
| Configured in | `.codex/agents/*.toml` (project) or `~/.codex/agents/*.toml` (personal); global limits under `[agents]` in `config.toml` |
| Loads / runs | Codex spawns an agent thread when you ask for one, or when applicable `AGENTS.md` or skill instructions request delegation |
| Scope & precedence | Project or personal files; a custom agent named like a built-in (`explorer`) wins over the built-in |

## Build the scenario

| Step | What you write or run | Where |
|---|---|---|
| 1 | Save the agent file | `ticket-service/.codex/agents/reviewer.toml` |
| 2 | Keep the `github` server from the [MCP page](https://ai-sw-factory.mellicci.dev/fundamentals/mcp/codex) | `.codex/config.toml` |
| 3 | Ask: `have the reviewer check this change against issue #42` | Codex CLI |
| 4 | Watch or switch threads | `/agent` |

```toml
name = "reviewer"
description = "Reviews the current change in ticket-service against the issue's acceptance criteria and the team conventions. Use after implementing an issue, before opening a pull request. Read-only."
model = "<model>"   # any model /model lists; a different one gives a second opinion
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
Run `git diff main...HEAD` and read the whole change.
Read the issue named in the request with the github server.
Check each acceptance criterion against the diff.
Check conventions: a changed route in src/routes/ needs a test in test/;
files in src/db/migrations/ are never hand-edited.
Return pass or fail per criterion, then findings with file:line.
Never edit files.
"""
```

`mcp_servers` is omitted, so the reviewer inherits the parent's `github` server. The `model` line gives a second opinion from a model that may differ from your main session. To make delegation routine, add a line to `AGENTS.md` such as "After implementing an issue, have the reviewer check the change before opening a pull request." The parent then waits for the reviewer's summary.

## Specifics

### Built-in and saved agents

| Kind | Name or location | Notes |
|---|---|---|
| Built-in | `default` | General-purpose fallback |
| Built-in | `worker` | Execution-focused: implementation and fixes |
| Built-in | `explorer` | Read-heavy codebase exploration |
| Saved, project | `.codex/agents/*.toml` | Shared through version control |
| Saved, personal | `~/.codex/agents/*.toml` | Yours across projects |

The documentation doesn't say which of a project and a personal file wins when both use the same `name`.

### Definition fields

| Field | Required | Purpose |
|---|---|---|
| `name` | Yes | The name Codex uses to spawn or refer to the agent; the source of truth, not the filename |
| `description` | Yes | Guidance on when Codex should use it |
| `developer_instructions` | Yes | The core instructions |
| `model`, `model_reasoning_effort` | No | Override the model and effort |
| `sandbox_mode` | No | For example `read-only` |
| `mcp_servers`, `skills.config` | No | Agent-specific servers and skill settings |

Codex loads each file as a configuration layer, so other supported `config.toml` keys also work. The documentation notes the format may evolve.

### What a subagent inherits

| | Inherited by default | Override |
|---|---|---|
| Sandbox and approvals | The parent's policy and permission mode | `sandbox_mode` in the file, but the parent's live `/permissions` changes or `--yolo` are reapplied to the child anyway |
| MCP servers, skills | The parent's, when the file omits `mcp_servers` or `skills.config` | Set them in the file |
| Model and effort | Parent's model and effort | File value, else the spawn request, else `[agents]` defaults, else parent |
| Conversation | Not shared; the subagent works from its instructions and the brief | n/a |

If a spawn request or an `[agents]` default picks a model without an effort, the model's default effort applies. A file that sets only `model` keeps that effort; set `model_reasoning_effort` too to choose another.

### Invocation, foreground and background

| | Detail |
|---|---|
| Trigger | A direct request ("spawn one agent per point", "have the reviewer check this") or applicable `AGENTS.md` or skill instructions |
| Parallel | Several agents can run at once; Codex waits until all requested results are in, then consolidates them. Say "wait for all" to be explicit |
| Inspect | `/agent` or `/subagents` opens a picker of agent threads |
| Steer | Ask Codex to steer, stop or close a subagent thread |
| Approvals | In the CLI, a request from an inactive thread appears as an overlay with the source thread; press `o` to open that thread |
| Non-interactive | An action that needs a new approval fails, and the error goes back to the parent workflow |

The documentation describes waiting for results rather than a separate foreground and background mode. The IDE's background-agent panel lists active subagents.

### Limits and cost

| Setting (`[agents]`) | Effect |
|---|---|
| `enabled` | Default `true`; `false` turns off the multi-agent tools |
| `max_concurrent_threads_per_session` | Cap on open spawned threads, excluding the primary; Codex picks the default when unset. `max_threads` is a legacy alias |
| `default_subagent_model`, `default_subagent_reasoning_effort` | Defaults for spawned agents; an explicit spawn value wins |
| `interrupt_message` | Default `true`; records a model-visible note when a turn is interrupted |

Each subagent does its own model and tool work, so subagent runs use more tokens than a comparable single-agent run. Higher reasoning effort adds time and tokens. The documentation suggests parallel agents for read-heavy work and care with parallel writers.

## Gotchas

- **Ask, or instruct.** Codex spawns subagents on a direct request or when `AGENTS.md` or a skill asks for it. A `description` alone does not start the reviewer.
- **Read-only can be overridden.** `sandbox_mode = "read-only"` can be overridden at runtime: the parent's live `/permissions` changes or `--yolo` are reapplied to the child. Choose the parent's mode before delegating.
- **No new approvals headless.** In non-interactive runs a subagent that needs an approval fails, and the parent sees the error.
- **Match the filename to `name`.** It is only a convention, but `name` decides how Codex refers to the agent.
- **The summary is all you get.** Put what you need, such as `file:line` per finding, into the instructions.