<!-- Codex worktrees: merging parallel agent branches · https://merget.ai/guides/codex-worktrees-merge -->

# 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.

Merget team · Nov 13, 2026 · 4 min read

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](https://learn.chatgpt.com/docs/environments/git-worktrees).

- Worktrees live under `$CODEX_HOME/worktrees` by default. Change the worktree root in Settings > Worktrees.
- A worktree starts in detached HEAD at the head of the branch you chose. It is not a named branch yet.
- List gitignored files a chat needs, such as `.env`, in a `.worktreeinclude` file at the repository root.
- Codex keeps your 15 most recent managed worktrees by default and saves a snapshot before it deletes an older one.

## 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.

|  | Local | Worktree |
| --- | --- | --- |
| Where it runs | Your main checkout | A separate checkout under the worktree root |
| Branch | Whatever you have checked out | Detached HEAD until you select “Create branch here” |
| Good for | The task you are working on now | Tasks that run in parallel or in the background |
| Moving between them | Hand off to a worktree | Hand 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

- Missing local files. A new worktree has only tracked files. Add `.env` and similar files to `.worktreeinclude` so Codex copies them in.
- No branch to push. A worktree starts in detached HEAD. Select “Create branch here” before you commit and push.
- A branch that is already checked out. Git allows one checkout per branch, so move the chat with Hand off or switch the other checkout to a different branch.
- A worktree that has gone. Codex keeps the 15 most recent managed worktrees and snapshots older ones, so reopen the chat to restore it.

## 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](https://merget.ai/how-it-works) 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](https://merget.ai/benchmarks/conflict-resolution) from real merges with one model call each.

Running Claude Code or Cursor alongside Codex? See the [Claude Code worktrees guide](https://merget.ai/guides/claude-code-worktrees-merge) and the [Cursor worktrees guide](https://merget.ai/guides/cursor-worktrees-cloud-agents).

## 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](https://merget.ai/how-it-works), or [sign up free](https://sema.merget.ai/login) and connect one repository.

### Merging git worktrees from parallel Claude Code agents

Claude Code’s --worktree flag gives each session its own checkout and branch. Set them up, land the branches, and stop them colliding at merge time.

Merget team · Nov 13, 2026 · 4 min read

[Open](https://merget.ai/guides/claude-code-worktrees-merge)

### Claude Code agent teams: landing the pull requests

Agent teams coordinate the work between Claude Code sessions, not the merge. Set a team up, avoid overwrites, and land what it produces.

Merget team · Nov 13, 2026 · 4 min read

[Open](https://merget.ai/guides/claude-code-agent-teams-pull-requests)

### Cursor worktrees and cloud agents: landing the pull requests

Cursor runs agents in git worktrees on your machine and in cloud VMs that push branches. See how both work and how to keep the pull requests landing.

Merget team · Nov 13, 2026 · 4 min read

[Open](https://merget.ai/guides/cursor-worktrees-cloud-agents)

[All guides](https://merget.ai/guides)
