Codex Subagents: Parallel Work Without Token Waste

OpenAI's current Codex documentation says subagent workflows consume more tokens than comparable single-agent runs because every child performs its own model and tool work. At the same time, independent lanes can run concurrently and can use a different model from the primary agent.

Parallelism wins only when the lanes are genuinely independent and the cost of decomposition, coordination, and integration is lower than waiting for their sum. A fleet can make all three metrics worse when scopes overlap or every worker needs the previous answer.

The first two answers are mandatory. If either is no, keep the work in the primary thread.

Good first lanes include codebase mapping, documentation research, log triage, independent test investigation, and focused review. Keep ambiguous requirements, sequential work, and changes in one hot file together.

If the task is not understood well enough to split, establish its boundaries first with an implementation-ready Codex Plan Mode workflow. Delegation should execute a decision-complete task graph, not multiply an unresolved prompt.

The primary agent should not repeat the same investigation “just in case.” It waits for the required evidence, checks it, resolves disagreements, and asks a focused follow-up only when the result is incomplete.

Avoid having every worker rerun the entire repository build. Give each lane targeted checks, then run the required integrated validation once after the findings or changes are combined.

Without explicit configuration, Codex subagents inherit the parent model and reasoning effort. That is convenient, but it can make a fleet of simple workers as expensive as the orchestrator.

Escalate a worker when its lane needs broader context or difficult judgment. Do not save credits by routing a security decision or cross-cutting architecture choice to a model that cannot reliably close it.

OpenAI's September 12, 2026 credit rate card makes the routing opportunity visible, but it does not predict the cost of a complete task.

A weaker worker may need more context, more attempts, or expensive recovery. A vague fan-out can also multiply the same repository scan across every child. Compare the measured cost and outcome of the complete workflow, not one cell in the table.

You do not need a large catalog of personas. Start with the smallest fan-out that maps to real independent questions. Add another worker only when it owns a new lane.

Use up to three Codex subagents only for independent work.

- explorer: map the affected code paths; read-only; return file and symbol evidence.
- test analyst: find relevant tests and gaps; read-only; return exact commands and risks.
- docs researcher: verify current external APIs; read-only; return primary-source links.

Keep requirements, architecture, implementation, synthesis, and final verification in the primary
thread. Do not duplicate a worker's task. Wait for all required results, resolve conflicts, then
return one integrated plan. Workers must not spawn more workers.

The number three is an example, not an ideal fleet size. The active task boundary matters more than the role name, so each worker still receives a full contract.

Role: read-only API compatibility researcher.
Question: which endpoints and fields change in the target framework version?
Scope: official framework documentation and the repository's API adapter only.
Non-goals: no implementation, dependency updates, or broad architecture proposal.
Evidence: primary-source links plus exact adapter files and symbols.
Output: answer, evidence, contradictions, recommended next action; under 500 words.
Stop: report a blocker if the version or target adapter cannot be established.
Do not spawn subagents.

[agents]
max_concurrent_threads_per_session = 4
default_subagent_model = "gpt-5.6-terra"
default_subagent_reasoning_effort = "medium"

# .codex/agents/fast-explorer.toml
name = "fast_explorer"
description = "Read-only inventory, extraction, and targeted code searches."
model = "gpt-5.6-luna"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Answer only the delegated question. Return concise file and symbol evidence.
Do not edit files, expand scope, or spawn subagents.
"""

# .codex/agents/reviewer.toml
name = "reviewer"
description = "Focused correctness and regression review with concrete evidence."
model = "gpt-5.6-terra"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
Prioritize real correctness and regression risks. Cite files, symbols, and reproduction steps.
Return findings only; do not modify code or spawn subagents.
"""

Project agents live under .codex/agents/; personal agents live under ~/.codex/agents/. Current Codex precedence considers explicit spawn choices,[agents] defaults, parent values, and the selected custom-agent file. Specify both model and reasoning effort when the pairing matters.

Subagents inherit the active sandbox and permission mode and may observe the same mutable checkout. Separate conversation threads therefore do not protect files from concurrent edits.

One current Codex issue reports parent and subagent threads observing different branch state in a shared checkout. It is one report, not proof of universal behavior. The guardrail is still cheap: every writing lane states its expected working directory and branch, verifies both, and stops instead of guessing when they disagree.

Public reports include role drift, shared-checkout branch drift, abnormal token amplification, and duplicated local rollout history. They justify monitoring and stop conditions, but they do not establish normal Codex behavior or a universal token multiplier.

An external Anthropic engineering report reaches a compatible architectural conclusion: its orchestrator-worker research system fit breadth-first independent work, consumed substantially more tokens, and fit dependent coding work less well. Those measurements apply to that research system—not Codex.

Native Codex provides subagents, model routing, thread controls, and custom-agent configuration. Supercode is not the source of that orchestration.

• Every worker owns an independent question with a checkable deliverable.
• The primary thread retains requirements, decisions, synthesis, and acceptance.
• The model and reasoning effort match the lane instead of inheriting accidentally.
• Read-only is the default; writing lanes are isolated.
• Every writing lane checks cwd, branch, and status before editing.
• Worker prompts include scope, non-goals, evidence, output, and stop conditions.
• Nested delegation is forbidden unless it is explicitly bounded.
• Workers return compact evidence rather than raw exploration history.
• The primary agent resolves contradictions and runs integrated validation.
• Token and credit usage are observed after the run instead of assumed.

If the task cannot pass the independence and deliverable gates, use one Codex thread. The cheapest subagent is the one you did not need to spawn.