A Codex subagent is useful when it removes a bounded piece of work from the main thread. It is not useful merely because a task is large. The decisive question is whether the work can proceed independently and return a compact result without forcing several agents to negotiate the same files, assumptions, or decisions.
Current local Codex releases enable subagent workflows by default in the desktop app, CLI, and IDE extension. You can ask for delegation directly, and applicable AGENTS.md or skill instructions can request it as well. Each subagent performs its own model and tool work, so a parallel workflow consumes more tokens than a comparable single-agent run. OpenAI's Subagents documentation recommends beginning with read-heavy work such as exploration, tests, triage, and summarization, while treating parallel writes more carefully.
The unit of delegation is an outcome, not a persona
Naming an agent “security expert” does not make the assignment independent. A strong delegated task has a defined input, a boundary, a completion condition, and a return format the parent can evaluate.
Consider a branch review. “Spawn five reviewers” creates duplicate reading and five differently shaped opinions. A better split might be:
- one read-only agent maps changed execution paths and reports file references;
- one checks correctness and security only after receiving that map;
- one runs the relevant tests and separates reproducible failures from environment failures;
- the main thread reconciles evidence, severity, and next actions.
Some of that work can run at the same time; some has a real dependency. Preserving that dependency is more important than maximizing concurrency.
Before spawning, ask four questions:
| Question | Good sign | Warning sign |
|---|---|---|
| Can the task finish without another agent's unresolved decision? | It has its own evidence and stop condition | It needs a shared design to stabilize first |
| Is the write surface separate? | Read-only or disjoint files | Several agents will edit the same interface |
| Can the result be compressed? | Findings, references, uncertainty, and next decision | A raw transcript or unbounded log dump |
| Who owns the merge? | The main thread has explicit judgment criteria | “Let the agents agree” is the only plan |
If the warning column dominates, keep the work sequential or delegate only the exploratory part.
Ask for division, waiting, and evidence
Codex can orchestrate spawning, follow-up instructions, waiting, and result collection. Your prompt still needs to specify what good orchestration means for this task. For example:
textReview this branch against main with three subagents. 1. Have explorer map the affected execution paths. Read only. 2. Have a reviewer look for correctness, security, and missing-test risks. 3. Have a test agent run only the relevant test targets and classify failures. Wait for all three. Return one consolidated report that cites files and commands, separates confirmed issues from hypotheses, and notes any scope each agent did not inspect. Do not modify the repository.
That prompt makes five decisions explicit: the branches, their permissions, the wait condition, the evidence format, and the parent's consolidation responsibility. For an implementation workflow, add a writer only after the problem and file ownership are clear. Give that writer a narrow change boundary and an observable validation command.
Permissions come from the parent workflow
Local subagents inherit the current sandbox or permission mode. In the app and IDE, choose the permission mode below the composer before asking Codex to delegate. In an interactive CLI session, approval requests can surface from a background agent thread; the overlay identifies its source, and o opens that thread before you approve or reject. In a non-interactive run that cannot surface a new approval, the restricted action fails and the error returns to the parent.
Live parent overrides matter too. If you changed permissions interactively or started with a broader command-line mode, Codex reapplies that live choice when it spawns a child, even when a custom agent file contains different defaults. Delegation is therefore not an isolation boundary by itself.
A defensible operating pattern is:
- keep explorers, documentation checkers, and reviewers read-only;
- assign write permission only after a specific change is understood;
- avoid overlapping file ownership among active writers;
- keep external writes, credentials, installation, and destructive actions behind explicit approval;
- inspect the source thread when an approval arrives unexpectedly.
Supervision differs by client
The work is conceptually the same across local clients, but the controls are not interchangeable.
- In the Codex desktop app, open a subagent thread from the activity shown in the main chat. You can ask Codex to steer a running agent, stop it, or close completed threads.
- In the Codex CLI, use
/agentto switch among agent threads and inspect progress or results. - In the IDE extension, the background-agent panel, when available, shows status and lets you stop agents or open a thread.
Intervene when an agent crosses its boundary, loses the requested evidence format, or discovers a dependency that invalidates the original split. Waiting for a polished summary is wasteful if the work is already pointed at the wrong files.
Custom agents are for repeated responsibility
Codex includes three built-ins: default, worker, and explorer. A custom agent is worthwhile when a responsibility recurs and needs a stable model, reasoning effort, sandbox, tool set, or instruction boundary. Personal agents live under ~/.codex/agents/; project-scoped agents live under .codex/agents/. Each standalone TOML file requires name, description, and developer_instructions.
tomlname = "migration_reader" description = "Read-only agent that maps migration impact before implementation." model = "gpt-5.6-terra" model_reasoning_effort = "high" sandbox_mode = "read-only" developer_instructions = """ Trace actual call paths and configuration dependencies. Return evidence with file references, assumptions, and unresolved decisions. Do not edit files or propose unrelated cleanup. """
The current official model guidance starts with gpt-5.6 for demanding, ambiguous agents, uses gpt-5.6-terra for faster read-heavy support work, and reserves gpt-5.6-luna for narrow, repeatable tasks. Treat those as current defaults, not permanent truths: model access depends on the account, authentication route, and client.
Global controls live under [agents], including agents.enabled, agents.max_concurrent_threads_per_session, default subagent model and reasoning effort, and interruption-message behavior. Multi-agent tools are currently enabled by default. If you need to understand how user, project, profile, and command-line layers interact, use the separate Codex config.toml guide instead of pasting a full configuration just to start delegating.
Consolidation is where correctness returns
A clean summary can still be wrong. The parent should reopen the strongest evidence before accepting a result:
- confirm which tests actually ran and whether their environment matched the target;
- follow security findings to a reachable execution path;
- check that “no references found” reflects a sufficient search scope;
- separate observations, inferences, and recommendations;
- resolve duplicate or contradictory findings before assigning severity.
The main thread should retain requirements, decisions, and final accountability. Subagents should absorb bounded intermediate work and return distilled evidence. That division protects context and can save elapsed time when the branches are independent, but it never removes the need for one owner to verify the combined answer.
If the unresolved question is which coding-agent product fits your development style, rather than how to delegate inside Codex, continue with the Claude Code versus Codex comparison.
