Codex Subagent Configuration in Practice: Safe Exploration, Verification, and Delivery

A practical guide to configuring role-based Codex subagents for parallel exploration, verification, and safe implementation.

Codex subagents in practice

Large tasks become unreliable when requirements, search output, and test logs share one thread. Codex subagents let the **main thread own decisions and synthesis while bounded exploration, verification, and implementation run in separate threads**. Current Codex releases enable subagent workflows by default, and the CLI exposes threads through `/agent`.

> These examples were checked on 2026-09-08 with Codex CLI 0.153.4 and the official documentation. Agent keys and model availability are version- and account-dependent. Always validate copied configuration with `codex exec --strict-config ...`.

1. Divide work by independence

Good parallel work is independent and read-heavy: security review, test-gap analysis, and API-documentation checks can run together. Concurrent edits to the same files create conflicts.

• **Explorer:** read-only file discovery, call-path tracing, impact mapping

• **Verifier:** run tests, lint, and builds; report exact evidence

• **Worker:** implement the smallest change inside explicit file ownership

• **Main:** own requirements, priority, the final diff, and conclusions

Each subagent performs its own model and tool work, so it uses more tokens than a comparable single-agent run. Parallelize only when tasks are genuinely independent and can return short summaries.

2. Global settings and named roles

User configuration lives in `~/.codex/config.toml`; trusted projects can add `.codex/config.toml`. This example uses model slugs verified in the local catalog.

```toml

[agents]

default_subagent_model = "gpt-5.4-mini"

default_subagent_reasoning_effort = "low"

max_concurrent_threads_per_session = 4

[agents.explorer]

description = "Read-only codebase mapping and evidence gathering."

config_file = "agents/explorer.toml"

[agents.verifier]

description = "Run tests, lint, build, and report exact failures."

config_file = "agents/verifier.toml"

```

Relative `config_file` paths resolve from the declaring config file. Official docs also describe standalone personal roles under `~/.codex/agents/` and project roles under `.codex/agents/`. The current standalone schema requires `name`, `description`, and `developer_instructions`. Because the format evolves, do not mix registry and auto-discovery patterns until strict validation passes.

Read-only explorer

```toml

name = "explorer"

description = "Read-only explorer for locating code and tracing behavior."

developer_instructions = """

Inspect only. Cite files and symbols. Do not edit or propose broad refactors.

Return a concise evidence map to the parent.

"""

model = "gpt-5.4-mini"

model_reasoning_effort = "low"

sandbox_mode = "read-only"

```

Workspace-write verifier

Tests may need to create caches or snapshots, making `workspace-write` practical. Still forbid product-code changes explicitly.

```toml

name = "verifier"

description = "Runs checks and reports exact failures."

developer_instructions = """

Run the requested checks. Do not fix application code.

Report the command, exit status, failing assertion, and likely root cause.

"""

model = "gpt-5.4"

model_reasoning_effort = "medium"

sandbox_mode = "workspace-write"

```

A crucial caveat: children inherit the parent turn's live sandbox and approval policy. Runtime permission changes can override role-file defaults. Treat a role file as configuration, not as the security boundary; minimize the parent session's permissions first.

3. Validate before use

```bash

codex --version

codex features list

codex exec --strict-config -s read-only \

"Inspect the repository configuration and return a short summary. Do not edit files."

```

`--strict-config` rejects fields unknown to the installed binary. Common failures are: using `reasoning_effort` instead of `model_reasoning_effort`; a missing `config_file`; or a model slug unavailable to the account. Check `/model`, the local catalog, and an actual run. Start a new session after changing config.

4. Invocation patterns

State the division and completion conditions in the prompt:

```text

Review this branch against main. Run explorer read-only to map changed paths,

and verifier to execute relevant tests and the build. Run them in parallel,

wait for both, then return one summary with file paths, commands, and evidence.

Do not edit code.

```

For implementation, use a staged gate:

```text

Run explorer and verifier in parallel first. Only after the main agent confirms

the root cause, start one worker. The worker owns only src/parser.ts and makes

the smallest fix. Finally, verifier reruns the same commands.

```

Use `/agent` to inspect active threads, steer them, or stop unnecessary work.

5. Reproducing the role split in Claude Code

Claude Code also supports custom subagents, but it does not reuse Codex's TOML agent configuration. Project-scoped roles are commonly defined as Markdown files such as `.claude/agents/explorer.md` and `.claude/agents/verifier.md`. The accurate distinction is not “Claude has no agents,” but that **it does not share Codex's TOML structure, so equivalent separation is expressed through Markdown role files**.

```markdown

name: explorer

description: Map code locations and call paths without editing.

tools: Read, Grep, Glob

model: haiku

Do not modify files. Return a concise evidence map to the parent.

```

```markdown

name: verifier

description: Run tests and builds and report exact failures.

tools: Read, Grep, Glob, Bash

Do not fix application code. Report commands, exit codes, and failing points.

```

Use `~/.claude/agents/` for personal roles and `.claude/agents/` for project roles shared with the repository. Frontmatter keys and tool names can evolve, so check the official Claude Code documentation and the installed version.

6. Safety checklist

• Parallelize reads; serialize writes to shared files.

• Give each agent one question, one deliverable, and one stop condition.

• Verify commands, exit codes, and diffs instead of trusting self-reported success.

• Expect approval-requiring actions to fail in non-interactive runs that cannot surface prompts.

• Avoid `danger-full-access` and approval bypass unless an external sandbox guarantees containment.

• Never paste secrets, auth files, or personal paths into prompts or logs.

• Start with a small thread cap and increase it only after measuring a bottleneck.

7. A repeatable recipe

Use **Map → Decide → Change → Verify**: two explorers inspect independent areas; the main agent deduplicates findings and fixes scope; one worker owns the edit; a verifier reruns clean checks and reviews the diff; the main agent decides completion from evidence.

The advantage is not the number of agents but the quality of their boundaries. Read-only exploration, evidence-first verification, and explicit file ownership keep the main context clean and failures traceable.

References

• https://developers.openai.com/codex/subagents

• https://developers.openai.com/codex/config-reference

• https://developers.openai.com/codex/config-file/config-advanced

• https://developers.openai.com/codex/cli