Subagents Design - Defining and Using Specialized Agents

Codex Subagents run specialized agents in separate contexts and consolidate their results through the parent agent. They fit large codebase exploration and reviews with independent perspectives.

Skills compared with Subagents

Capability	Skill	Subagent
Purpose	Add procedures and knowledge	Create an independent work context
Execution	Current agent applies it	Separate agent performs it
Good fit	Repeatable workflow	Parallel exploration or specialist review

Subagents add model and tool work, so they are unnecessary for small changes. Codex spawns them only when explicitly requested.

Divide a review

Independent review perspectives can include security, specification compliance, regressions, and missing tests.

Spawn one subagent for each review perspective.
Wait for all agents.
Return one consolidated list ordered by severity.
Do not edit files.

Ask the parent agent to wait, remove duplicates, order findings by severity, and state unresolved questions.

Define a custom role

[agents.security-reviewer]
description = "Review changed code for concrete security vulnerabilities without editing files."
config_file = "agents/security-reviewer.toml"

The description should state both responsibility and boundaries. A review-only agent should explicitly avoid edits.

Decide When to Parallelize

Subagents work best when tasks are independent, results can be merged, agents do not edit the same files, and the value of parallel exploration exceeds additional token cost. Start with read-only parallel work.

Next, Hooks implementation adds deterministic actions to the Codex lifecycle.