Orchestrating Multiple Parallel Agents

You have a two-week sprint with eight tickets. Working them sequentially means finishing five if you are lucky. Working them in parallel — with three Codex agents running on worktrees, two cloud tasks handling refactors, and you reviewing and merging results — means finishing all eight with time to spare. Multi-agent workflows are how teams multiply their output without multiplying their headcount.

What You’ll Walk Away With

• A framework for decomposing work into parallelizable agent tasks
• Concrete patterns for running agents across worktrees, cloud, and local threads simultaneously
• Merge strategies that prevent conflicts when combining results from multiple agents
• Guardrails that prevent runaway token consumption

The Decomposition Framework

Not all work parallelizes well. Use this decision tree:

Parallelize when:

• Tasks modify different files or directories
• Tasks are independent (no data dependency between them)
• Each task can be verified independently (its own tests, its own lint check)

Serialize when:

• Tasks modify the same files
• Task B depends on the output of Task A
• You need human judgment between steps

The Three-Surface Pattern

Codex App (Worktrees)

Best for: Feature implementation, bug fixes, and any work that needs Git isolation.

Open multiple Worktree threads in the App, each based on the same branch:

Thread 1: "Implement the /api/v2/orders endpoint with Zod validation"
Thread 2: "Add database indexes for the orders table queries"
Thread 3: "Write integration tests for the orders API using the test helpers in tests/utils"

Each runs in its own worktree. When all complete, sync each to the same feature branch using “Apply.”

CLI (codex exec)

Best for: CI pipelines, scripted workflows, and headless automation.

# Run three agents in parallel using background processes
codex exec --full-auto "Fix the TypeScript strict mode errors in src/auth/" &
codex exec --full-auto "Update the OpenAPI spec to match the current routes" &
codex exec --full-auto "Add missing JSDoc comments to all exported functions in src/utils/" &
wait

Each exec invocation gets its own session. Use --json for machine-readable output.

Cloud Tasks

Best for: Heavy workloads, delegated work, and best-of-N strategies.

# Submit multiple cloud tasks
codex cloud exec --env prod-env "Migrate the user service from Express to Fastify"
codex cloud exec --env prod-env --attempts 3 "Optimize the search query performance"

Cloud tasks run in isolated containers. Use --attempts 3 for best-of-N when multiple approaches exist.

Prompt: Parallel feature decomposition

Before starting parallel work, ask Codex to plan the decomposition:

“I need to add a notification system with email and Slack channels. Break this into independent tasks that can be implemented in parallel by separate agents. Each task should modify different files and be independently testable. Output a numbered list with the prompt I should give to each agent.”

Merge Strategies

When multiple agents complete work on the same project, you need a strategy for combining results:

Sequential Apply (Safest)

Sync worktrees to your feature branch one at a time, resolving conflicts as they arise:

1. Sync the most foundational change first (e.g., database migration)
2. Sync the next dependent change (e.g., API implementation)
3. Sync the least dependent change last (e.g., tests, docs)
4. Run the full test suite after all syncs

Parallel Branches + PR Merge

Each agent creates its own branch. Open PRs from each branch to the feature branch. Use GitHub’s merge queue to combine them.

Cloud Best-of-N

For the same task, run 3 attempts and pick the best:

codex cloud exec --env ENV_ID --attempts 3 "Optimize the database query in orders.ts"

Review all three solutions and choose the one with the best performance characteristics.

Guardrails

Multi-agent workflows multiply both productivity and cost. Set these guardrails:

• Limit concurrent threads: 3-5 worktree threads is practical; more creates review bottleneck
• Use GPT-5.1-Codex-Mini for simple tasks: Reserve GPT-5.3-Codex for the complex work
• Monitor with /status: Check remaining limits before launching a batch of tasks
• Set timeouts for exec: Long-running tasks may indicate the agent is stuck

When This Breaks

• File conflicts between agents: Two agents edited the same file. The “Apply” sync method attempts a patch; if it fails, use “Overwrite” for one and manually merge the other.
• Context window exhaustion: Each thread has its own context window. If a thread gets slow, start a new one and reference the previous thread’s output.
• Rate limit errors: Too many concurrent cloud tasks can hit your plan’s per-5-hour limit. Stagger submissions or prioritize.
• Inconsistent results: Agents do not share context. If Agent B needs to know what Agent A did, either serialize them or include the relevant context in Agent B’s prompt.

What’s Next

• Batch Operations — Scale parallel work to dozens of files or repositories
• Review Strategies — Efficiently review the output of multiple agents
• Context Patterns — Keep each agent focused with the right context