Codex Subagents: Parallel Work Without Losing Control

Codex subagents are separate agent threads that handle bounded parts of a larger task. The main thread delegates work, subagents operate with their own context and tools, and the main thread collects their results into one response or implementation.

The feature is useful for two reasons. First, independent work can happen concurrently. Second, noisy exploration, test logs, and research stay out of the main conversation, where requirements and decisions need room to remain legible.

The trap is assuming more agents automatically means more progress. Parallelism amplifies the quality of your decomposition: clean boundaries become faster work; vague or overlapping boundaries become duplicated investigation, conflicting edits, and a larger review queue.

What to delegate first

Good early subagent tasks are read-heavy and independently verifiable:

• Map three unrelated subsystems before planning a refactor.
• Review one diff separately for security, correctness, and missing tests.
• Run or inspect independent test suites and return only failures with likely owners.
• Research separate framework questions against official documentation.
• Triage logs from independent services or time windows.

Write-heavy delegation needs stronger boundaries. Two agents editing the same component tree or shared schema can create a conflict that costs more than the parallel run saved. Assign disjoint files, use isolated worktrees, or keep one agent as the sole editor while others return evidence and recommendations.

Ask for a shape, not just “use agents”

A strong orchestration prompt defines roles, outputs, and the join point:

Review this branch against main with three subagents:
 
1. Security reviewer: find exploitable behavior changes and cite files and lines.
2. Test reviewer: map changed behavior to existing tests and identify concrete gaps.
3. Maintainer: find correctness or maintainability risks, ignoring style-only issues.
 
All three are read-only. Wait for every result, deduplicate overlapping findings,
then return one severity-ordered report. Do not edit files.

This is better than “spawn three reviewers” because each worker has one lens, one artifact, and one boundary. The parent knows when to wait and how to consolidate.

Design tasks around dependencies

Before delegating, draw the dependency shape:

independent research ─┐
test inventory ───────┼─> implementation owner ─> verification ─> final review
API investigation ───┘

The first three tasks can run concurrently. Implementation cannot responsibly begin until their contracts are clear. Verification depends on the integrated change. Spawning all five at once would create speculative work rather than useful parallelism.

Use subagents for the branches, not every box. Keep the main thread responsible for requirements, architectural decisions, and the final acceptance criteria.

Manage agent threads

In Codex CLI, /agent lets you inspect and switch between agent threads. Supported app and IDE surfaces expose subagent status and let you open individual threads. You can also ask Codex to steer a running agent, stop it, or close completed threads.

Do not monitor every line of output by default. Ask workers to return compact evidence:

• files and symbols inspected
• findings with severity or confidence
• commands run and results
• unresolved questions
• a recommendation to the parent, not a transcript

The point is to protect the main context from intermediate noise while preserving enough provenance to audit the conclusion.

Permissions propagate

Subagents inherit the parent turn's live sandbox and approval choices. Select the parent permission boundary before delegating. A custom agent can narrow itself further — for example, a reviewer can set sandbox_mode = "read-only" — but do not assume a child will magically receive access the parent lacks.

Interactive approval requests can surface from an inactive thread. In headless workflows that cannot ask for a new approval, the protected action fails and the failure returns to the parent. Unattended multi-agent plans therefore need all required permissions and dependencies established before the fan-out begins.

Create a custom agent

Codex includes general-purpose built-in roles. For repeatable specialization, create a TOML file in .codex/agents/ for the repository or ~/.codex/agents/ for personal use:

# .codex/agents/security-reviewer.toml
name = "security_reviewer"
description = "Read-only reviewer for exploitable behavior, trust boundaries, and unsafe data flow."
sandbox_mode = "read-only"
model_reasoning_effort = "high"
developer_instructions = """
Review only for security-relevant behavior.
Trace untrusted input to sensitive sinks, cite concrete files and symbols,
and distinguish exploitable findings from hardening suggestions.
Do not edit files. Return findings ordered by severity with reproduction steps.
"""

The required fields are name, description, and developer_instructions. Other supported Codex settings can specialize the model, reasoning effort, sandbox, MCP servers, or enabled skills. If a custom agent omits them, Codex resolves them from explicit spawn values, agent defaults, and the parent configuration.

Keep the description about when the role should be used. Keep developer_instructions about how it behaves once selected. A narrow role is easier for the parent to route and easier for a reviewer to trust.

Put global limits in config

Configure the overall system under [agents] in config.toml:

[agents]
enabled = true
max_concurrent_threads_per_session = 4
default_subagent_reasoning_effort = "medium"

Cap concurrency at the number of useful independent tasks, not the largest number the client permits. Every agent creates token cost, tool load, coordination work, and output someone must review.

One owner integrates

A successful multi-agent workflow ends with a single owner who:

1. Waits for the required results.
2. Reconciles contradictions and removes duplicate findings.
3. Applies or merges changes in a controlled order.
4. Runs the complete verification suite on the integrated state.
5. Reviews the final diff against the original goal.

Subagents can accelerate branches of work. They do not remove the need for one coherent definition of done.

Official reference: Codex subagents.