Codex CLI Subagents: Delegation That Stays Inspectable

What a subagent is in Codex

A subagent is a delegated agent that Codex starts for one piece of work and then collects back into the main thread. The main thread keeps requirements, decisions, and the final output; subagent threads hold the noisy middle — exploration notes, test logs, and command output. Codex calls the result a subagent workflow.

Current local Codex releases enable subagent workflows by default. Activity appears in the CLI, the desktop app, and the IDE extension, and the main thread waits for the requested results before producing a consolidated response.

When to delegate

Delegate work that is independent and read-heavy. Keep it in the main thread when it is sequential, write-heavy, or depends on decisions not yet made.

The rule OpenAI gives is explicit: start with parallel agents for read-heavy tasks such as exploration, tests, triage, and summarization, and be more careful with parallel write-heavy workflows because agents editing at once create conflicts and coordination overhead.

Invoking subagents

You trigger delegation by asking for it directly. Codex can also follow applicable AGENTS.md or skill instructions that request delegation. There is no separate "subagent mode" flag to remember; the prompt carries the division of work.

Three properties make that prompt work:

• Division — one agent per concern, named explicitly.
• Join — "wait for all three" tells Codex to collect before continuing.
• Output contract — summarize by category with file references, not raw logs.

In the CLI, /subagents inspects and switches between agent threads while they run. When many agents are active, Codex waits for all requested results and then returns one consolidated response.

You can also encode the expectation in project instructions, so a review request does not need to restate it every time:

## Review workflow

- For branch reviews, spawn one subagent per category: security, tests, maintainability.
- Subagents are read-only. They report findings; they do not edit.
- Return a summary per category with file and line references.

Keeping delegation inspectable

Delegation fails quietly when you cannot see what each agent did. Three controls keep it legible:

1. Threads, not summaries alone. Open subagent threads in the CLI with /subagents, or in the app's activity panel. A summary is the agent's claim; the thread is the evidence.
2. Explicit models and effort. If you do not configure a subagent model or model_reasoning_effort, the subagent inherits the parent's settings. A model selected without an explicit effort uses that model's default. Set [agents] defaults in config.toml or per-agent files when you want cheap scans and expensive synthesis to coexist.
3. A stable output shape. Ask for findings as a list with file, line, severity, and the failing input. Free-form prose is harder to merge across three threads.

For repeated work, define custom agents with their own instructions and model configuration. The configuration reference covers where those settings live and how they merge with project config.

Failure modes

• Token cost. Each subagent runs its own model and tool calls. A three-agent review can cost several times a single-agent pass. Budget for it or scope the agents down.
• Write conflicts. Two agents editing the same file produce a merge problem the orchestrator has to resolve. Keep subagents read-only unless the work is cleanly partitioned by directory.
• False independence. Agents that need each other's findings are not parallel work. They will duplicate effort or return contradictory conclusions.
• Summary drift. The main thread only sees what the subagent returns. If the summary omits the failing command, the main thread cannot verify the claim.
• Scope expansion. "Review the repo" invites each agent to wander. Name the branch, the diff, or the directories.

The visibility caveat

In July 2026, a report on the Codex repository described message payloads between parent and sub-agent being encrypted (PR #26210). The practical consequence is that you can see that delegation happened and read the returned summary, but the raw instructions passed between agents may not be readable. The write-up on that change covers the developer pushback and the open issue.

Delegation is one tool-use pattern among several. Tool-use patterns covers the sequential and conditional shapes that do not need parallel agents, and Codex as reviewer applies delegation to a review pass. If you are still choosing a harness, compare Codex with Claude Code and OpenCode.

Sources

• Subagents
• Codex CLI
• Configuration reference