How to run multiple Codex agents in parallel (2026)

Short answer

To run multiple Codex agents in parallel, give each one its own git worktree so no two sessions write to the same files, then keep track of them somewhere other than your memory. For two or three sessions, the Codex CLI in tmux with manual worktrees works, and the Codex app's Worktree mode does the same with a toggle. Past that, the cost is bookkeeping: ports, .env, node_modules, red CI and which branch merged. Orchestrator.inc (formerly Agent Orchestrator) handles that bookkeeping per session and sends CI and review events back to the Codex session that owns the PR. This guide covers all three.

At a glance

Codex app and Cloud task details are as of October 2026.

The problem in practice

You have four small issues: a login bug, a billing field, a flaky test and a docs fix. Codex can do each one in a few minutes. If you run them one after another, you wait. If you start four Codex sessions in the same checkout, they edit the same files, fight over the same dev server port, and leave you with one messy branch.

What you want is four independent branches, four agents, and one place to see which PRs are green.

The manual way

1. Codex CLI in tmux

The Codex CLI is open source and runs on macOS, Linux and Windows, signed in with ChatGPT or an API key. Start a tmux session with one named window per task:

tmux new-session -d -s codex
tmux new-window -t codex -n auth
tmux new-window -t codex -n billing
tmux attach -t codex

Do not start two sessions in the same checkout. Two agents editing the same file at once can overwrite each other's changes.

2. One worktree per session

A git worktree is a second working copy of the same repository on its own branch. Create one per task:

cd ~/code/web
git worktree add ../web-auth -b feature/auth
git worktree add ../web-billing -b feature/billing

In the auth window:

cd ~/code/web-auth && codex

In the billing window:

cd ~/code/web-billing && codex

Each worktree is a full checkout without your gitignored files, so install dependencies and copy .env into each before Codex starts the dev server. If two sessions run a dev server, give each a different PORT.

When a branch is merged, clean up:

git worktree remove ../web-billing
git branch -d feature/billing
git worktree prune

3. The Codex app's Worktree mode

As of October 2026, the Codex app runs on macOS and Windows as a mode inside the ChatGPT desktop app. Each chat has a mode: Local works in the project directory, Worktree creates a git worktree under $CODEX_HOME/worktrees in detached HEAD, and Cloud runs in a remote workspace. A .worktreeinclude file copies gitignored files such as .env into each worktree. "Create branch here" gives a finished worktree a codex/ branch, and Handoff moves a chat between Local and Worktree. Worktrees are available only inside the desktop app, not the CLI.

4. Cloud tasks

Cloud tasks each get a workspace built from a published environment, work against GitHub repositories, and can commit or open a PR. You can start and check them from the web, the mobile app, the desktop app or the CLI. Local and cloud usage share one ChatGPT allowance, and API-key users do not get cloud features.

Where the manual way gets expensive

• Ports. Every worktree runs the same dev server config, so the second one tries to bind the same port as the first.
• Empty checkouts. A fresh worktree has no .env and no node_modules, so the build fails and the agent spends context diagnosing setup. Full installs per worktree also add up on disk.
• Losing track. Several terminals look identical, and after a few days it is hard to remember which branches merged. The Codex app's sidebar groups by project and thread, which helps, but it does not show PR or CI state.
• Rebase churn. Each merge into main can leave the other branches needing a rebase, and nothing tells the other sessions.
• CI and review live on GitHub. A failing check or a review comment is yours to find and paste back into the right session.

Tips

• One issue per session keeps branches independent and rebases rare.
• Symlink node_modules instead of reinstalling it in every worktree.
• Set a different PORT per session before any dev server starts.
• For work that should continue with the laptop closed and off, use a Codex Cloud task, run the Orchestrator host on your own server or VM, or use Orchestrator Cloud. Use Orchestrator when you want each PR followed through CI and review.
• Pair a Claude Code reviewer with Codex workers so the review comes from a different model.
• When Orchestrator runs on your laptop, the laptop needs to be on for automations and the mobile app. The Stay Awake setting keeps it awake, and mobile access keeps working with a MacBook lid closed. A remote host or Orchestrator Cloud keeps agents working while the laptop is off.

Doing this with Orchestrator.inc

Orchestrator is a desktop app for macOS, Windows and Linux. Running it on your own machines is free and open source (Apache-2.0), with no account needed; you bring your own agent subscriptions or API keys. Optional Orchestrator Cloud plans, for agents that keep working while your laptop is closed, are Starter at $20/month and Pro at $40/month, with Enterprise pricing on request. It runs Codex either in a structured Chat view or in the Codex CLI's own terminal UI, alongside Claude Code, Cursor, OpenCode and the rest of its agents.

1. Install and add the project

Download the app and add your repository as a project. A local daemon runs on 127.0.0.1 and keeps its state under ~/.ao. To run sessions on a server or cloud VM instead, install the Orchestrator host there and add it under Settings, Remote hosts; one app can drive several hosts.

2. Configure the worktree once

In the project settings, set postCreate commands, symlinks for node_modules and .env, and environment variables every session needs (worktree workspace docs). Every new Codex session starts ready to build.

3. Spawn Codex sessions

From the desktop, click New session, choose Codex, and pick Chat or Terminal. From the CLI, ao spawn does the same.

Each session gets its own worktree on a named branch. Codex sessions can switch between Chat and the terminal UI later without losing the worktree. If one issue suits a different agent, pick Claude Code or another harness for that session instead; it lands on the same board.

4. Read the board

Sessions sit in Working, Needs you, In review or Ready to merge, based on session, PR, CI and review facts. No status is set by hand.

5. Let the PR loop run

Once Codex pushes a PR, Orchestrator discovers it and polls GitHub or GitLab, with no webhooks or GitHub App. Failing checks go to the owning session with names, links and the end of the failed job's log, review comments arrive as focused feedback, and merge conflicts go to the same session (review loop guide). You can have a Claude Code reviewer look at each Codex PR by turning on autoReview for the project. When the card reaches Ready to merge, click Merge. Orchestrator never merges on its own.

6. Clean up

ao session cleanup --dry-run

The dry run lists what cleanup would remove, and cleanup skips any worktree with uncommitted changes.

Follow the parallel issues guide to run your first two Codex sessions on real issues. For a product-level comparison, see Orchestrator.inc vs the Codex app.

Frequently Asked Questions

How do I run multiple Codex agents in parallel?

Give each Codex session its own git worktree and branch with git worktree add, start Codex inside each one, and keep them open in tmux windows or terminal tabs. The Codex app's Worktree mode does the same inside the ChatGPT desktop app, and Orchestrator.inc creates the worktree, runs setup and tracks the PR for each session.

Can I run several Codex CLI sessions at the same time?

Yes. Each one should run in its own git worktree, or at least its own directory, so they never edit the same file. tmux or terminal tabs are enough to keep them open; the harder part is remembering which one owns which branch.

Does the Codex app's Worktree mode work from the CLI?

No. As documented, worktrees are available only in Codex inside the ChatGPT desktop app, as of October 2026. From the CLI you create worktrees with git worktree add, or let Orchestrator create one per session.

Does Orchestrator.inc use my ChatGPT plan or an API key for Codex?

Either. Orchestrator runs the Codex CLI you already have installed and never proxies model calls, so Codex is billed exactly as it would be in a plain terminal: against your ChatGPT plan, or at API rates if you signed in with a key.

Can I mix Codex and Claude Code on the same board?

Yes. Orchestrator supports 38 coding agent harnesses, and each session picks its own. A common setup is Codex workers with a Claude Code reviewer, or the reverse. The parallel issues guide on docs.orchestrator.inc shows how to set it up.