How to run multiple Codex CLI agents in parallel

Start one codex per terminal and give each agent its own git worktree, so no two of them write to the same files. A worktree is a second checkout of the same repository in another directory: create it with git worktree add, start Codex inside it, and merge its branch after you have reviewed the work. Codex also has three built-in routes to parallel work: worktree chats in the ChatGPT desktop app, cloud tasks and subagents.

Two agents in one working tree overwrite each other

Codex CLI treats the directory where you start it as the project for the chat. Run codex in two terminals in the same directory and each chat keeps its own context, but they share one working tree: one set of files, one index, one checked-out branch. One agent's half-finished edit shows up in the other's test run and diff, and a checkout or reset by either changes the files under the other.

OpenAI's guidance on long-running work says to run chats concurrently but not let two chats change the same files, and to give parallel coding chats separate checkouts with worktrees.

Agents in different repositories are already isolated. Start each with codex --cd ~/code/api, where --cd (short form -C) sets the working directory.

Git worktrees give each agent its own checkout

From the repository, create one worktree per task. Each command makes a new directory and checks out a new branch in it:

cd ~/code/shop
git worktree add -b checkout-flow ../shop-checkout
git worktree add -b fix-login ../shop-fix-login main

-b names the new branch, the path is where the checkout goes, and an optional last argument sets the starting point (the current HEAD if omitted). Start one agent in each, in separate terminals:

codex --cd ../shop-checkout
codex --cd ../shop-fix-login

git worktree list shows every checkout with its commit and branch:

$ git worktree list
/Users/you/code/shop            089d9ae [main]
/Users/you/code/shop-checkout   089d9ae [checkout-flow]
/Users/you/code/shop-fix-login  089d9ae [fix-login]

A worktree lives wherever you point the path; a sibling of the main checkout is a tidy choice. Its .git is a file that points to .git/worktrees/<name> in the main repository, where git keeps that worktree's HEAD and index. Commits and branches are shared with every other checkout.

When a branch is merged, remove the worktree and then the branch:

git worktree remove ../shop-checkout
git branch -d checkout-flow

git worktree remove refuses a worktree that contains modified or untracked files, use --force to delete it; add --force when you are sure nothing in it matters. The branch survives removal, hence the second command. If you deleted the directory by hand, git worktree prune clears the stale record.

Two properties catch people out:

• One branch, one worktree. Checking out a branch another worktree already has fails with fatal: 'checkout-flow' is already used by worktree at '/Users/you/code/shop-checkout'.
• Only tracked files come along. Anything git ignores (node_modules, .env, build output) is missing until you install or copy it.

What Codex itself offers for parallel work

Worktree chats in the ChatGPT desktop app

On the desktop, Codex is part of the ChatGPT desktop app (codex app opens it, and /app moves the current CLI session there, on macOS and Windows). A new Codex chat runs in Local, Worktree or Cloud. With Worktree selected, Codex creates a git worktree from the branch you pick and runs the chat in it:

• Location. $CODEX_HOME/worktrees, which is ~/.codex/worktrees by default. Change it under Settings > Worktrees > Worktree root.
• Branch. None by default: the worktree starts in a detached HEAD. Create branch here makes it a branch, and Hand off moves the chat and its code to your local checkout.
• Setup. A local environment's setup script runs when the worktree is created, and .worktreeinclude lists ignored files, such as .env, to copy in.
• Cleanup. Codex keeps your 15 most recent managed worktrees by default and snapshots one before deleting it.

These apply to worktrees the app manages; the docs say .worktreeinclude does not apply to worktrees you create yourself from the command line.

Cloud tasks

Codex Cloud gives each task its own workspace and can keep working while your computer is asleep. A task runs in a published cloud environment, so your local files, running processes and VPN access are not transferred to it automatically. codex cloud opens a picker of cloud chats, and these submit a task and bring a result back:

codex cloud exec --env ENV_ID "fix the flaky checkout test"
codex apply TASK_ID

codex apply applies that cloud chat's latest diff to your local repository. The CLI reference marks codex cloud as experimental.

Subagents inside one session

Current Codex releases enable subagent workflows by default. Ask directly ("spawn one agent per point, wait for all of them, then summarize") and Codex runs the agents in parallel and returns one consolidated response; /agent switches between their threads. They inherit your sandbox policy, use more tokens than a single-agent run, and are capped by agents.max_concurrent_threads_per_session. OpenAI recommends them for read-heavy work such as exploration, tests and triage, and warns that agents editing code at once can create conflicts. Subagents split one task; they do not replace a worktree per task.

Resuming sessions and telling them apart

Codex saves each interactive session locally, with transcripts under ~/.codex/sessions. To get back to one:

codex resume
codex resume --last
codex resume --last --all
codex resume checkout-flow

codex resume opens a picker. --last skips it and resumes the most recent chat from the current working directory, so inside a worktree it picks up that worktree's agent; adding --all widens it to any directory. A final argument resumes one session by ID or by name.

Name a session with /rename checkout-flow so the last form works. /title sets what the terminal tab title shows (project, git branch, status and more), /statusline does the same for the footer, and /status prints the active model, approval policy and writable roots.

The TUI's notifications tell you when a terminal you are not looking at needs you. The sample configuration lists them as on by default, firing when the terminal is unfocused. In ~/.codex/config.toml you can limit them to the two events that matter here:

[tui]
notifications = ["agent-turn-complete", "approval-requested"]

Approval and sandbox settings for agents you are not watching

Codex has two separate controls. The sandbox mode sets what commands can touch, and the approval policy sets when Codex must stop and ask. For a version-controlled folder Codex recommends the Auto preset, which is the workspace-write sandbox with on-request approvals, and network access is off by default:

codex --cd ../shop-checkout --sandbox workspace-write --ask-for-approval on-request

In that mode an agent reads, edits and runs commands inside its workspace without asking, and asks before editing outside it or using the network. With one worktree per agent, each workspace is that agent's own checkout. Before you walk away:

• A pending approval stops that agent until you answer. --ask-for-approval never (-a never) removes the prompts in any sandbox mode, and the sandbox still holds.
• Commits may need approval. In workspace-write mode some environments keep .git read-only, including the Git directory a worktree's .git file points to, which the docs give as the reason git commit may still require approval.
• Older flags have changed. --ask-for-approval takes on-request or never, the untrusted policy is retired, and codex exec --full-auto is deprecated in favor of --sandbox workspace-write. codex exec defaults to a read-only sandbox.
• Automatic review. approvals_reviewer = "auto_review" sends eligible approval requests to a reviewer agent instead of you, without widening the sandbox; it uses extra model calls.
• Full access. --dangerously-bypass-approvals-and-sandbox (alias --yolo) removes both controls; the reference says to use it only inside an externally hardened environment.

Practical limits

• Usage. Local messages and cloud chats share your plan's usage allowance, and weekly limits may also apply. /status shows what you have left.
• Merge conflicts. Worktrees stop agents overwriting each other's files, not two branches changing the same lines. Split tasks by area of the code, merge one branch at a time and rebase the rest.
• Review. Every agent ends with a diff someone has to read. /diff shows it and /review asks Codex to review the working tree, but OpenAI's advice is to treat Codex's output like any other pull request. Start with two or three agents and add more only while you still read every diff.
• Disk. Each worktree carries its own files, dependencies and build caches.

What to check when a Codex worktree fails

The documentation covers worktree problems in several places, not under one error message. The documented requirements and fixes:

1. A git repository. Worktree chats only work in projects that are part of one.
2. The setup script. A local environment's setup script runs automatically when Codex creates the worktree. Its configuration lives in the .codex folder at the project root; in a repository with several projects, open the directory that contains that folder.
3. Ignored files. Worktrees inherit only files checked into git, so the troubleshooting page points to a setup script or .worktreeinclude for dependencies and local config.
4. A branch in use. fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>' means another checkout has that branch; check out a different branch there, or use Hand off.

If a chat only appears stuck, first check whether Codex is waiting for an approval.

How Armadai runs Codex

Armadai is a native macOS app that puts Claude Code and Codex agents for several projects on one canvas. It runs Codex in two kinds of tile, both using your installed Codex and your own account. A Codex CLI tile is Codex in a terminal. A Codex Agent tile is a chat-style view with streamed responses, approval controls, file-change review and saved conversations: when Codex asks for permission you see the command, folder and reason and accept, decline or cancel in the tile, and you can fork from a response into a new worktree.

Task hand-off is the part closest to this guide. On a task board, open Hand-off and choose Run with Codex. Armadai starts an agent if one is needed, gives the run its own Git worktree and tracks the task through to review, where successful work comes back as a draft pull request. A sidebar shows which sessions across your projects are working, idle or waiting for approval.

Your Mac's resources and your Codex usage limits still apply. Armadai is paid software for macOS with no free plan, at $20 a month or $120 a year after a 7-day free trial that requires a payment method. If creating worktrees by hand and watching a few terminals works for you, the commands above are all you need, and the ChatGPT desktop app manages Codex worktrees for you on macOS and Windows. The same choice comes up when running Claude Code across multiple projects.