Codex Subagents Guide: When Parallel Agents Help—or Slow You Down

Three agents do not automatically make a task three times faster. The real bottlenecks are decomposition and integration. If every branch waits on another result or edits the same code, the merge can cost more than the parallel run saved.

OpenAI recommends starting with read-heavy work such as exploration, testing, triage, log analysis and summarization. Independence—not agent count—is the useful variable.

Subagents reduce context pollution

Large repository scans, test logs and document comparisons can bury requirements and decisions in the main thread. The official guide describes this as context pollution and context rot.

A subagent performs noisy work in another thread and returns a summary. The main agent keeps the user contract, boundaries, integration and final judgment visible.

Good and bad parallel work

A task is a good candidate when A can finish without B, each has a distinct surface, and the return format is clear.

Shared component edits, sequential migrations and work that depends on one unresolved architecture decision should stay serial until the dependency is removed.

• Good: module exploration, independent tests, document summaries, competing hypotheses
• Risky: shared-file edits, common schemas, dependency chains, tiny single changes

A good delegation brief is bounded

“Analyze the project” duplicates the main task. Give each agent a question, read scope, write authority and return format. For write work, assign non-overlapping ownership.

Keep product judgment with the main agent. Subagents return evidence and options; the main thread reconciles conflicts and chooses the implementation.

Agent A: read auth files and tests; return a table of login failure paths; do not edit.
Agent B: reproduce the failing integration test; return the minimal command and ten relevant log lines; do not edit.
Agent C: check official library docs for session-expiry behavior in the installed version.
Main agent: compare all three, select one cause, implement and verify.

Wall-clock speed and token cost are different

Every subagent performs separate model and tool work, so total tokens can exceed a single-agent run. The benefit is elapsed time and isolation of noisy context.

If each subtask takes two minutes, startup, summary and integration overhead can dominate. Delegate meaningful independent blocks, not fragments of one small patch.

Assign ownership before parallel writes

When concurrent edits are necessary, give agents non-overlapping files or packages. Let the main agent integrate shared types and root configuration afterward.

Review diffs, tests and interface compatibility centrally. Delegation does not delegate away verification responsibility.

A 30-second decision rule

If two results must wait on each other, run them serially. If they touch the same file, redraw ownership. If you cannot specify the return format in one sentence, narrow the delegation.

Begin with independent read-heavy work. Add parallel writes only after the workflow demonstrates a real bottleneck reduction.

Frequently asked questions