GuideAugust 31, 2026

How to Run Multiple Codex Agents in Parallel

Use the real Codex CLI in one isolated workspace per task, then review each result before it reaches main.

To run multiple Codex agents safely, isolate every independent task in its own Git worktree. The official Codex app can manage worktrees for Codex-only workflows. Agentastic runs the same Codex CLI alongside Claude Code, Gemini, Cursor, and other agents, while adding containers, remote hosts, browser testing, and multi-provider review.

A developer running four OpenAI Codex agents in separate Git worktrees

Choose the workflow that matches the job#

WorkflowBest whenWhat you manage
Codex app worktreesYou want a first-party Codex-only experienceCodex project setup and review flow
Manual worktrees plus Codex CLIYou want no additional workspace applicationWorktrees, terminals, setup, status, ports, review, cleanup
AgentasticYou want multiple providers, native terminals, containers, browser verification, or remote/cloud executionTask boundaries and final review

OpenAI's official worktree documentation explains how Codex runs independent chats in separate checkouts, handles local/worktree handoff, copies ignored files, and cleans up managed worktrees.

Why one checkout cannot host parallel Codex edits#

Codex sessions are independent, but files are not. If two sessions edit the same checkout, they share uncommitted changes, generated files, dependency directories, and the Git index. A session can test code that already contains another session's half-finished edits.

A worktree gives each task a physical checkout. Every result becomes an independent diff you can keep, revise, or discard.

Option 1: use Codex's first-party worktrees#

The Codex app can create a managed worktree for a new chat. OpenAI documents three useful properties:

  • Each chat stays associated with its worktree.
  • Work can be handed between the background worktree and the local checkout.
  • Ignored local files can be copied with .worktreeinclude.

This is a strong default when every worker is Codex and you want the first-party surface.

Option 2: run the Codex CLI in manual worktrees#

Create one branch and directory per task:

bash
git fetch origin git worktree add -b agent/auth-tests \ ../app-auth-tests origin/main git worktree add -b agent/cache-fix \ ../app-cache-fix origin/main

Start Codex from each checkout:

bash
cd ../app-auth-tests && codex cd ../app-cache-fix && codex

Manual worktrees are universal and transparent. At three or four sessions, however, terminal naming, waiting approvals, setup scripts, dev servers, and review queues become the real work.

Option 3: run parallel Codex workspaces in Agentastic#

1. Install and verify Codex#

bash
npm install -g @openai/codex which codex codex --version

Sign in through Codex before launching it from Agentastic. Agentastic uses the provider's existing authentication, configuration, skills, and MCP servers.

2. Open your repository and choose Worktree mode#

In Agent Home:

  1. Select the repository.
  2. Choose the base branch.
  3. Select Codex.
  4. Keep Worktree selected.
  5. Name the task.
  6. Send a prompt with an explicit validation command.

Example:

text
Fix the flaky token refresh test in the authentication module. Do not change the public session API. Preserve the existing retry limit. Run only the authentication test target first, then the full unit suite if it passes. Summarize the race condition and every file changed.

Repeat for independent tasks. Each Codex session receives its own branch, checkout, terminal or Chat transcript, and diff.

3. Use one source of repository instructions#

Codex reads AGENTS.md, so keep durable project rules there:

markdown
# Repository instructions - Run `npm test -- auth` for authentication changes. - Do not edit generated clients under `src/generated`. - Keep public API changes backward compatible. - Never run production migrations from a development task.

Task-specific constraints belong in the prompt. Repository-wide rules belong in version control, where every parallel session sees the same contract.

4. Make the checkout runnable before Codex starts#

Use .agentastic/setup.sh for dependencies and ignored configuration:

bash
#!/usr/bin/env bash set -euo pipefail for file in .env .env.local; do if [ -f "$AGENTASTIC_MAIN_REPO_PATH/$file" ] && [ ! -f "$file" ]; then cp "$AGENTASTIC_MAIN_REPO_PATH/$file" "$file" fi done npm ci

Do not make the agent spend its first turn discovering how to boot the project. A reproducible setup script improves every provider, not only Codex.

5. Choose task boundaries before adding concurrency#

Parallelize tasks that can produce independent pull requests:

  • Fix unrelated failing tests.
  • Add coverage in separate packages.
  • Implement independent endpoints.
  • Compare two alternative implementations where only one survives.
  • Let Codex implement while a fresh Claude or CodeRabbit session reviews.

Sequence tasks that share a schema, central interface, generated artifact, or mutable database.

6. Use attention routing instead of polling terminals#

Agentastic shows whether each session is running, waiting, finished, or failed. Codex Chat also supports mid-turn steering where the provider exposes it. This lets you supervise by exception instead of opening every terminal every few minutes.

7. Test the result where it was produced#

Each worktree should be able to build and run independently. Start its development server and verify the result in Agentastic's browser. Agents can use the dev browser CLI to inspect the page, fill forms, read console errors, and capture screenshots.

For non-UI changes:

  • Re-run the focused tests.
  • Inspect the diff rather than trusting the transcript.
  • Check migrations and generated files separately.
  • Confirm no secrets or local paths entered the patch.

8. Review with a fresh context#

The agent that wrote a change carries the assumptions that produced it. A separate review session starts with a cleaner perspective.

Agentastic can send the captured diff and commit context to Codex review, Claude Code, CodeRabbit, Greptile, or a custom reviewer. Use multiple reviewers for security-sensitive or architectural changes, then validate their findings yourself.

Worktree, container, remote, or cloud?#

Agentastic can launch Codex in several execution modes:

  • Worktree: fastest local isolation for normal code changes.
  • Container: tighter runtime, dependency, mount, and network boundaries.
  • Remote SSH: use your own development machine or server.
  • Cloud provider: run on connected Modal, Fly.io, or Vercel environments while the Mac is offline.

Use a worktree until you have a concrete reason to isolate more than repository files.

Avoid the most common parallel-Codex mistakes#

Sending one vague feature to five agents#

Concurrency does not repair an unclear specification. Split the feature into independent, reviewable outcomes first.

Letting every worktree use the same database#

File isolation cannot prevent two migrations or test suites from mutating one shared service. Give each task its own database, schema, container, or serialized test lane.

Starting more work than you can review#

The queue that matters is not "agents running." It is "diffs waiting for a careful human." Cap concurrency when that queue grows.

After one branch changes a shared assumption, update or rebase dependent worktrees before accepting their results.

Start with two tasks#

Pick two independent issues, launch one Codex workspace for each, and take both through setup, execution, verification, review, and cleanup. Once that loop is boring, increase concurrency.

Download Agentastic for macOS or see the dedicated Codex integration page.

Sources and further reading#