Codex CLI subagents
Codex supports multi-agent workflows: the main agent can delegate work to subagents running in separate threads. Subagent workflows are enabled by default in current releases (agents.enabled = true, features.multi_agent = true). Codex delegates when you ask directly, or when AGENTS.md/skill instructions request it.
Built-in agents
| Agent | Role |
|---|---|
default | General-purpose fallback |
worker | Execution-focused |
explorer | Read-heavy exploration |
A custom agent with the same name as a built-in takes precedence over the built-in.
Custom agents
Custom agents are standalone TOML files:
~/.codex/agents/— personal agents.codex/agents/— project-scoped agents
Required fields per file: name, description, developer_instructions. Optional fields include model, model_reasoning_effort, sandbox_mode, mcp_servers, and skills.config.
# .codex/agents/security-reviewer.toml
name = "security-reviewer"
description = "Read-only reviewer that audits changes for security issues"
developer_instructions = """
You are a security-focused code reviewer. Never modify files.
Report findings with file:line references and severity.
"""
sandbox_mode = "read-only"
model_reasoning_effort = "high"The file is loaded as a config layer for the spawned session; omitted settings inherit from the parent. Resolution order for model/effort: explicit spawn value → [agents] default → parent’s value.
Spawning and coordinating subagents
The multi-agent tools available to the parent agent:
| Tool | Purpose |
|---|---|
spawn_agent | Start a subagent thread |
send_input | Send input to a running subagent |
resume_agent | Resume a subagent thread |
wait_agent | Wait for a subagent to finish |
close_agent | Close a subagent thread |
In the TUI, /agent (or /subagents) switches the active thread so you can inspect or continue a subagent’s work.
Global settings
Under [agents] in config.toml:
| Key | Purpose |
|---|---|
enabled | Master switch (default true) |
max_concurrent_threads_per_session | Concurrency cap (legacy alias max_threads) |
default_subagent_model | Default model for spawned agents |
default_subagent_reasoning_effort | Default reasoning effort |
interrupt_message | Default true |
agents.<name>.config_file / agents.<name>.description | Declare roles in config |
Permissions
Subagents inherit the parent’s sandbox/permission mode; custom agents can override it (for example, forcing read-only for a reviewer agent, as in the example above).
Use cases and limitations
Good fits:
- Parallel read-heavy exploration (map a codebase, find all callers, audit for a pattern)
- Isolating a specialist role (security review, test writing) with its own instructions and sandbox
- Long background tasks while you keep working in the main thread
Cautions:
- Subagent workflows consume more tokens than single-agent runs.
- Be careful with parallel write-heavy work — agents editing the same files can conflict.
Last verified: 2026-09-07
Official sources:
- https://developers.openai.com/codex/subagents
- https://developers.openai.com/codex/config-reference
- https://developers.openai.com/codex/cli/slash-commands
AI coding tools evolve quickly. If you find outdated information, please open an issue or pull request.