Codex Agent Teams: Build a Manager-and-Worker Coding Setup

Short answer: build a Codex agent team by keeping one main thread responsible for the goal, constraints, and final integration, then delegate only independent pieces to bounded subagents. Give every worker a concrete deliverable, a path or component boundary, the commands it may run, and the evidence it must return. The manager waits for the results, checks conflicts, and decides what is accepted.

OpenAI's current documentation calls this a subagent workflow, not a separate “agent teams” product. The search phrase is still useful because the operating pattern feels like a small engineering team: a manager decomposes work, specialists handle narrow jobs, and one owner consolidates the result. Codex exposes these workflows in the app, CLI, and IDE.

The important part is not spawning the largest possible swarm. It is creating parallel work that stays cheaper to coordinate than doing the task in one thread. This guide shows a conservative setup for repository exploration, tests, review, and carefully isolated implementation.

Contents

• What Codex agent teams mean
• Choose work that actually benefits
• Give the manager one clear job
• Design bounded worker roles
• Write a delegation prompt
• Prevent overlapping writes
• Require evidence-based handoffs
• Set permissions before spawning
• Add custom agents only when useful
• Run a first repository pilot
• Diagnose common failure modes
• Copy the launch checklist

What “Codex agent teams” means in practice

A Codex subagent workflow begins in the main chat or CLI thread. That root thread can spawn specialized child threads, send them bounded tasks, inspect their progress, steer them, wait for results, and combine the returned findings. In the CLI, /agent opens the agent-thread view. The app and IDE expose similar activity through their agent panels.

The workers do their own reasoning and tool work, so parallelism consumes more tokens than a comparable single-agent run. It also moves noisy exploration, test logs, and review notes away from the main decision thread. That trade is worthwhile when the side tasks are genuinely independent and the returned summaries are smaller than the raw work.

That is a team shape, but not a license for every worker to edit everything. The root thread remains the integrator. It decides which results are compatible and whether a claimed success is supported by repository evidence.

Choose work that actually benefits from parallel agents

Start with read-heavy work. OpenAI's Codex guidance specifically points to exploration, tests, triage, and summarization as good parallel candidates. They can run independently, generate useful evidence, and rarely fight over the same file.

A promising task has at least two branches that do not depend on each other's intermediate output. Reviewing one pull request for security risks, test gaps, and maintainability fits. Asking three workers to repair the same authentication function does not.

• Good: map frontend data flow while another worker maps the API contract.
• Good: run unit tests, inspect recent error logs, and review a diff in parallel.
• Good: investigate three independent migration blockers and compare the results.
• Poor: ask several workers to modify one shared configuration file.
• Poor: split a tiny task whose delegation brief is longer than the work.

Parallelize evidence gathering first. Parallelize writes only when ownership boundaries are obvious and mechanically enforceable.

Give the manager one clear job: integrate verified work

The main thread should hold the user's request, non-negotiable constraints, repository rules, and the definition of done. It should not repeat every command a worker runs. Its job is to divide the work, preserve decisions, and reject handoffs that lack evidence.

A useful manager plan has four phases:

1. Frame: restate the goal, scope, protected areas, and required validation.
2. Divide: identify independent questions or disjoint implementation slices.
3. Collect: wait for every requested worker and request clarification when a handoff is incomplete.
4. Integrate: reconcile conflicts, run final checks, and report one result.

The manager should keep a small decision ledger: accepted assumptions, rejected approaches, files with exclusive ownership, and tests that must pass before completion. This prevents a late worker result from silently reopening a settled decision.

Design workers around bounded outcomes

“Help with the backend” is not a worker task. “Trace how a checkout request reaches the payment provider and return the five relevant files, the validation path, and two likely failure points” is. A bounded worker knows when it is finished and what evidence belongs in its handoff.

Every worker brief should answer six questions:

1. What exact question or change does this worker own?
2. Which files, directories, or systems are in scope?
3. What must it leave untouched?
4. Which commands or tools may it use?
5. What evidence proves the result?
6. When should it stop and report a blocker?

Use the smallest worker count that matches the task graph. Two strong branches often beat six vague ones. More workers create more summaries to compare, more assumptions to reconcile, and more opportunities for duplicated work.

Use a delegation prompt that names the work split

Codex can delegate after a direct request or when applicable project instructions ask for it. The most reliable prompt makes the partition explicit and tells the manager to wait before synthesizing.

Review this branch against main with three subagents.

Worker 1 — correctness:
- inspect changed behavior and edge cases
- do not edit files
- return findings with file references

Worker 2 — tests:
- identify missing coverage
- run the smallest relevant test set
- return commands, results, and gaps

Worker 3 — security:
- inspect trust boundaries and secret handling
- do not edit files
- return only actionable findings

Wait for all three workers. Reconcile duplicate findings, verify the
highest-risk claims yourself, then summarize by severity.

The prompt does not need to dictate every thought. It needs to make ownership, output, and synchronization unambiguous. “Wait for all three” matters: otherwise the manager may answer after the first plausible result and leave slower evidence unused.

Prevent overlapping writes before they happen

Parallel editing is where agent teams become expensive. Two sensible patches can conflict because they touch the same import list, migration, test fixture, or shared type. Do not assume subagent threads automatically provide branch or filesystem isolation.

Use one of three patterns:

• Read-only workers: workers investigate and propose; the manager makes the only edits.
• Disjoint paths: each worker owns a directory or file set that cannot overlap.
• Explicit worktrees: when your repository workflow supports them, create separate branches or worktrees and let the manager cherry-pick reviewed commits.

The first pattern is the safest default. It still gains speed from parallel analysis while keeping a single writer. Move to disjoint writes only after the team repeatedly demonstrates clean handoffs.

Require evidence-based handoffs

A worker's final message is an interface. If it returns “looks good,” the manager must redo the work. A useful handoff is compact but auditable: conclusion, evidence, commands, changed files, assumptions, and unresolved risks.

Outcome: PASS / NEEDS_CHANGES / BLOCKED
Scope inspected: paths or components
Findings: prioritized list with file references
Commands run: exact commands and exit status
Changes made: files and behavioral effect
Assumptions: facts not independently verified
Risks: what the manager should check next

The manager should sample the evidence. Open the referenced file, rerun a critical command, or inspect the diff. Delegation reduces the amount of raw work in the main context; it does not remove ownership of the final answer.

Set permissions before spawning the team

Subagents inherit the parent session's permission and sandbox mode. Choose that boundary before delegation. A worker should not receive broad write or network access merely because another worker needs it.

For a review team, read-only access is usually sufficient. A tester may need permission to run repository commands but not publish artifacts. An implementation worker may need writes inside the repository while deployment, secrets, and external mutations remain blocked.

Inactive agent threads can surface approval requests in interactive CLI use. Inspect which thread requested the action and why before approving. In non-interactive work, an operation that requires fresh approval should fail back to the manager rather than silently widening access.

Add custom agents only when the role repeats

Codex includes built-in default, worker, and explorer agent types. Begin there. If the same specialist brief appears across many tasks, define a custom agent under .codex/agents/ for a project or ~/.codex/agents/ for personal use.

A custom agent file requires a name, description, and developer instructions. Optional settings can tune the model, reasoning effort, sandbox, MCP servers, or skills. Keep the role narrow; “review database migrations for backwards compatibility and rollback risk” is easier to trust than “be our senior engineer.”

name = "migration_reviewer"
description = "Reviews database migrations and rollback safety."
developer_instructions = """
Inspect migrations, callers, deployment order, and rollback behavior.
Do not edit files. Return findings with file references and severity.
"""

Global agent settings control concurrency and nesting. The documented defaults allow six open agent threads and one level of spawned children. Treat those as ceilings, not targets. A first production workflow should normally use two or three workers.

Run a first repository pilot

Choose a medium-sized pull request with several independent review angles. Avoid a release emergency or a repository nobody understands. Record how long a normal single-thread review takes so the team has a baseline.

1. Ask the manager to restate scope and protected areas.
2. Spawn an explorer, tester, and reviewer in read-only mode.
3. Require all three handoffs before synthesis.
4. Let the manager verify the highest-risk claim from each worker.
5. Compare the consolidated findings with a human review.
6. Measure elapsed time, token usage, duplicated findings, and missed defects.

Success is not “three agents ran.” Success is a faster or more complete review with manageable coordination cost. If the manager spends longer reconciling vague reports than a single agent would have spent reviewing the branch, reduce the worker count or sharpen the briefs.

For long-running repository work that needs persistence beyond one interactive session, see the guide to running autonomous coding tasks with Codex. If the real need is a persistent hosted worker rather than parallel threads, compare AI agent hosting separately.

Diagnose the five common failure modes

1. Duplicate exploration. Workers received roles but no distinct questions. Rewrite the briefs around separate evidence.
2. Conflicting patches. Ownership overlapped. Return to a single writer or assign disjoint paths.
3. Context-free handoffs. Results lack file references or commands. Enforce the handoff contract.
4. Premature synthesis. The manager answered before slow workers finished. State the wait condition explicitly.
5. Permission drift. A broad parent mode gave every worker more access than necessary. Set the boundary before spawning.

There is also a quieter failure: unnecessary fan-out. Subagents consume their own context and tool calls. If one capable thread can complete a task cleanly, use one thread. A team should earn its overhead through independent work and better evidence.

Codex agent team launch checklist

• The task contains at least two independent branches.
• The manager owns scope, decisions, integration, and final verification.
• Every worker has a bounded outcome, scope, stop rule, and handoff format.
• Read-only analysis is parallelized before repository writes.
• Write workers own disjoint paths or explicit branches/worktrees.
• The parent permission mode is appropriate for every spawned worker.
• The prompt tells the manager which workers to spawn and when to wait.
• Handoffs include file references, commands, assumptions, and risks.
• The manager verifies critical evidence before accepting the result.
• The pilot measures elapsed time, usage, duplicated work, and missed defects.

Codex agent teams work best as a disciplined coordination pattern: one manager protects the goal, specialists handle independent evidence, and every result returns through a verifiable interface. Start with a read-only review team. Once that workflow is consistently useful, add custom roles or isolated write lanes one at a time.

Sources

• OpenAI Codex Manual
• OpenAI: Codex subagents
• OpenAI: Codex configuration basics
• OpenAI: Codex configuration reference