Guides
CodexGit worktrees

Codex worktrees: merging parallel agent branches

Codex runs each chat in its own git worktree so parallel tasks do not interfere. Turn the worktrees into pull requests and land them together.

In the Codex app, choose Worktree under the composer to run a chat in its own checkout. When the work is ready, use Create branch here, push the branch and open a pull request. Several Codex chats working in parallel produce several pull requests, and a merge queue that resolves conflicts keeps them landing.

How Codex uses worktrees

A Codex worktree is a second checkout of your repository that shares the same Git metadata, so several chats can work on one project without interfering. In the new chat view, select “Worktree” under the composer, choose the starting branch, and submit the prompt. Codex creates the worktree. See the Codex worktree docs.

From worktree to pull request

  1. Select “Create branch here” in the chat header to put the work on a named branch.
  2. Commit and push the branch.
  3. Open a pull request on GitHub.

To continue in your main checkout instead, select “Hand off” and move the chat to Local. Git allows a branch to be checked out in only one place, so if you see fatal: 'feature/a' is already used by worktree, check out a different branch in one of them or use Hand off.

Local and Worktree: foreground and background

Codex describes Local as the foreground and Worktree as the background. Use Local for the task you are steering, and worktrees for tasks that can run on their own while you work. Scheduled tasks in a Git repository run on dedicated background worktrees.

LocalWorktree
Where it runsYour main checkoutA separate checkout under the worktree root
BranchWhatever you have checked outDetached HEAD until you select “Create branch here”
Good forThe task you are working on nowTasks that run in parallel or in the background
Moving between themHand off to a worktreeHand off to Local

A workflow for several Codex tasks

  1. Start each task as a Worktree chat from the same up-to-date branch.
  2. If the project needs setup, pick a local environment so its setup scripts run in the new worktree.
  3. When a task is done, create a branch, push it and open a pull request.
  4. Let the pull requests land through a merge queue instead of rebasing each one by hand.

Common snags

Where parallel Codex tasks collide

Each chat started from the same commit. Once one pull request lands, the others are behind main. Edits to the same lines become merge conflicts. Edits to related code, such as a changed function signature and a new caller, merge cleanly and break the build. With several tasks running at once, each landing can send several chats back to repair their branches.

Landing the branches together

You can land them one at a time and rebase the rest, or put a merge queue in front of main. GitHub’s merge queue tests queued pull requests together and removes one that conflicts. Merget is a semantic merge queue for GitHub. It finds the pull requests that collide, including the ones Git merges cleanly, resolves the conflicts in queue order, and lands the result through your required checks and reviews.

Merget works from GitHub, so nothing changes in how Codex works. Merget starts in Advisory mode, where it reports the conflicts and changes no source code. To give your agent the queue’s findings and order, paste this into it:

Fetch and execute the instructions to set me up for Merget from https://sema.merget.ai/agent-setup/prompt.md

What changes with a queue that resolves conflicts

Without one, each landing sends the other Codex chats back to update their branches, and every update is more model use and another CI run. With one, a chat is finished when its pull request is open. In our benchmarks, Merget planned a queue of 40 merges in under 30 seconds and resolved 223 of 223 conflicted files from real merges with one model call each.

Running Claude Code or Cursor alongside Codex? See the Claude Code worktrees guide and the Cursor worktrees guide.

Questions

Where does Codex store worktrees?

Under $CODEX_HOME/worktrees by default. You can change the worktree root in Settings > Worktrees.

Why is my Codex worktree in detached HEAD?

Codex starts a worktree at a commit, not on a named branch. Use “Create branch here” in the chat header to create one.

Do worktrees stop Codex tasks conflicting?

They stop tasks overwriting each other’s files while they run. The branches can still conflict when they merge.

See how Merget resolves conflicts in queue order, or sign up free and connect one repository.