Codex — Part 6 — Subagents in Codex

Introduction

Part 5 covered packaging a repeatable procedure as a Skill. This post covers a related but different problem, the same one the Claude Code series raised in its own Part 6: a task worth doing, but whose intermediate work you have no reason to keep looking at afterward. Codex’s answer is subagents, run in parallel threads, with results consolidated back into your main conversation.

What Is a Subagent?

A subagent is a delegated agent Codex spawns to handle a specific task independently. Subagents run in parallel, letting the main thread stay focused on decisions while specialised agents handle exploration, testing, or analysis. Codex waits for the results it asked for, then returns a consolidated summary, keeping the noisy intermediate output on the subagent’s own thread.

Built-in Agents

Spawning a Subagent

Subagents currently spawn when you ask directly, or when your AGENTS.md or a skill’s instructions request it. Structure the request so the work is genuinely separable.

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 findings by category with file references.

Use /agent inside a session to switch between active threads and inspect what each one is doing.

Creating a Custom Subagent

Custom subagents are standalone TOML files, saved to a specific location depending on scope.

Each file requires name, description, and developer_instructions. sandbox_mode can restrict what the agent is allowed to do, the same idea as restricting tools on a Claude Code subagent.

Following on from the AGENTS.md example in Part 4, here is a read-only agent that audits PowerShell scripts against that same quality baseline.

# Save to .codex\agents\script-auditor.toml

name = "script-auditor"
description = "Reviews PowerShell scripts for quality baseline violations: missing StrictMode, aliases, untyped parameters. Use after writing or updating a script, or when asked to audit the scripts folder."
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
You are a PowerShell quality auditor. For each script you review, check for:
- Set-StrictMode -Version Latest present
- No aliases such as ? or % in place of full cmdlet names
- Typed parameters with validation attributes where appropriate
- Comment-based help header present

Report findings as a short list per file: what was checked, what passed,
and what needs fixing. Do not edit files yourself.
"""

When It Is Worth Delegating

Codex’s own guidance draws a clear line: subagents excel at read-heavy work, exploring a codebase, mapping test coverage, triaging logs, summarising documents. They are riskier for write-heavy work, since multiple agents editing files at once create conflicts and coordination overhead rather than saving time.

Controlling Parallelism

Two settings under [agents] in config.toml control how far delegation is allowed to go.

# %USERPROFILE%\.codex\config.toml
[agents]
max_threads = 6   # concurrent agent threads, default 6
max_depth = 1      # nesting depth, default 1: a child can spawn, a grandchild cannot

The default max_depth of 1 lets the root thread spawn direct children but stops a spawned agent from spawning further agents of its own, a sensible default before you have a feel for how much parallel work actually helps on your machine.

Final Thoughts

Subagents in Codex and Claude Code solve the same problem, keeping disposable intermediate work off your main thread, with different mechanics: explicit parallel spawning with a thread limit in Codex, versus a single delegated worker returning a summary in Claude Code. Both are about protecting the conversation you are actually trying to have, not about making any single task smarter.

Start with the built-in explorer agent for anything read-only, and only reach for a custom TOML agent once you notice yourself asking for the same kind of audit or research more than once.