How to run multiple Codex agents in parallel

Why two Codex sessions in one folder collide

Nothing stops you from running codex in two terminals in the same repository. The trouble is that both agents then edit one working tree on one branch: one agent's half-written change breaks the other's test run, both touch the same lockfile, and the final diff mixes two tasks you now have to untangle by hand.

A git worktree solves this. It is an extra checkout of the same repository in a separate folder, on its own branch, sharing one .git history. One worktree per agent means each agent has its own files, and everything it commits shows up as an ordinary branch you can review and merge.

What Codex offers built in (as of September 2026)

OpenAI ships three relevant options. They move fast, so check the linked docs for the current state.

• Codex CLI worktrees. Codex CLI 0.154.0 (September 9, 2026) added experimental worktree support: start a session in an isolated checkout with --worktree or the /worktree slash command, then browse and resume those sessions. Per the changelog, worktree support is enabled by default from 0.156.0 (September 22, 2026). The command reference describes /worktree as "Run the chat in a new Git worktree." Run codex --version to see which release you have.
• The Codex desktop app. Codex in the ChatGPT desktop app (macOS and Windows) has a Worktree mode. Per OpenAI's worktree docs, it creates worktrees in $CODEX_HOME/worktrees in a detached HEAD state, can run a setup script through a "local environment", keeps your 15 most recent Codex-managed worktrees by default, and has a Handoff flow to move a chat between the worktree and your main checkout.
• Codex cloud. codex cloud sends tasks to OpenAI-hosted containers instead of your machine, for example codex cloud exec --env ENV_ID "Fix the flaky auth test". Each task runs in its own container, so cloud tasks never collide with each other. The trade-off is that you configure a cloud environment and work leaves your machine.

The manual method below works on every Codex version, gives you control over folder and branch names, and works the same way for any other agent.

Step by step: one worktree per Codex session

1. Start from a clean commit. Commit or stash your current work, so every worktree starts from a known point.

2. Create a worktree and branch per task, next to the repo rather than inside it:

cd ~/code/myapp
git worktree add ../myapp-search -b feature/search
git worktree add ../myapp-csv -b fix/csv-export

-b creates a new branch from your current HEAD. For an existing branch, leave it out: git worktree add ../myapp-review existing-branch.

3. Prepare each worktree. Only tracked files are checked out, so install dependencies and copy local config:

cd ../myapp-search
npm install            # or pnpm install, uv sync, cargo build...
cp ../myapp/.env .env  # untracked files don't come along

4. Start Codex in each worktree. Either cd into it, or use the --cd (-C) flag to set Codex's working directory:

codex -C ~/code/myapp-search
codex -C ~/code/myapp-csv

Your AGENTS.md is a tracked file, so every worktree has its own copy of the project instructions. The sandbox and approval settings you normally use (--sandbox workspace-write --ask-for-approval on-request is OpenAI's suggested low-friction setup for local work) apply per session.

Running them side by side

A couple of terminal tabs are enough for two sessions. For more, use tmux so they survive a closed terminal and live in one place:

tmux new -s codex -c ~/code/myapp-search   # window 1: codex
# inside tmux:
#   Ctrl-b c   new window  → codex -C ~/code/myapp-csv
#   Ctrl-b ,   rename the window after its branch
#   Ctrl-b w   pick a window from a list
#   Ctrl-b d   detach; sessions keep running
tmux attach -t codex                          # back later

If you closed a session, codex resume continues a previous session by ID, or the most recent one. For keeping sessions alive after you close your laptop, the same approach applies as for Claude Code: see keeping agents running with the lid closed.

Gotchas

• Ports. Parallel dev servers can't all bind port 3000. Give each worktree its own (PORT=3001 npm run dev if your framework reads PORT) and tell the agent which one is its own.
• Dependencies per worktree. Every worktree needs its own install. It takes disk space, but one agent upgrading a package can't break another agent's build.
• Untracked files. .env, local certificates and similar files exist only where you put them. Copy what each worktree needs and keep them gitignored.
• Shared services. Worktrees isolate files, not your local database, Docker containers or caches. Use a separate database or schema per worktree if agents run migrations.
• One branch per worktree. Git won't check out a branch that is already checked out in another worktree, which keeps two agents off the same branch.
• Shared git state. Branches, tags and the stash are shared by all worktrees, so a git stash pop in one can pick up another's stash. Prefer commits.
• Usage limits. All sessions bill against the same ChatGPT plan or API key, so parallel agents use it up proportionally faster.

Reviewing and merging the work

Codex can review a branch before you merge it. From inside the worktree, codex review --base main reviews the branch against main, and codex review --uncommitted reviews changes not yet committed. Then commit and push the branch for a pull request:

cd ~/code/myapp-search
git add -A && git commit -m "Add full-text search"
git push -u origin feature/search     # open a PR

or merge it locally from the main checkout:

cd ~/code/myapp
git merge feature/search

When two branches touch the same code, merge one, then have the other agent run git rebase main in its worktree and resolve the conflicts.

Cleaning up

git worktree list                    # what exists
git worktree remove ../myapp-search  # refuses if there are uncommitted changes
git branch -d feature/search         # after it's merged
git worktree prune                   # clear records of folders you deleted by hand

The easier way: Maestro

Doing this by hand is fine for a few tasks. Once you run agents in parallel every day, the worktrees, ports and tabs are the part that wears you down. Maestro is a free desktop app that handles them: each workspace is a git worktree on its own branch with the agent's chat, a terminal and the diff in one window, and there's no cap on workspaces.

• Runs Codex with your own ChatGPT or OpenAI account, alongside Claude Code, Cursor, OpenCode, Kimi Code and Grok Build.
• Each workspace gets its own port ($WORKSPACE_PORT) and can run a per-repo setup script in every new worktree.
• Review diffs, comment inline, and open pull requests from the app. Follow every agent from your phone with Maestro Web.
• macOS, Windows and Linux.

More on the Codex side: a desktop GUI for Codex CLI. The Claude Code version of this guide is how to run multiple Claude Code sessions in parallel.