Running Claude Code and Codex Side by Side in One Repo with git worktree

Sometimes you want Codex to polish the UI while Claude Code is busy refactoring an API. But if you run both agents in the same directory, things go wrong quickly:

• One agent reads and overwrites a file while the other is still editing it.
• One agent runs git checkout or git stash, and the other agent's in-progress changes disappear or get mixed in.
• When a test or build fails, you can't tell whose change caused it.

The fix is simple: give each agent its own working directory and branch. You could clone the repository several times, but git has a feature built for exactly this: git worktree. This post walks through the setup for one person running Claude Code and Codex CLI concurrently, based on behavior we verified hands-on.

Tested with Claude Code 2.1.289, codex-cli 0.160.0 and git 2.43 on Linux. CLI behavior may change between versions.

1. What git worktree is

A normal repository has one .git (the repository data) and one working directory. A worktree lets you attach several working directories to a single shared .git.

Compared with cloning several times:

The last row matters. Git will not let one branch be checked out in two worktrees at once:

$ git worktree add ../proj2 worktree-api
fatal: 'worktree-api' is already used by worktree at '.../proj/.claude/worktrees/api'

So git itself prevents two agents from accidentally working on the same branch.

2. Creating worktrees by hand

Start manually to see how it works:

cd ~/work/proj
 
# Create a worktree with a new branch (a sibling directory outside the repo is recommended)
git worktree add ../proj-claude -b feat/api-refactor
git worktree add ../proj-codex  -b feat/ui-polish
 
git worktree list
# /home/me/work/proj         a1b2c3d [main]
# /home/me/work/proj-claude  a1b2c3d [feat/api-refactor]
# /home/me/work/proj-codex   a1b2c3d [feat/ui-polish]

Then run each agent in its own directory:

(cd ../proj-claude && claude)
(cd ../proj-codex  && codex)      # or: codex -C ../proj-codex

3. Built-in worktree support in the CLIs

Both CLIs can create worktrees for you. They differ in where they put them and how they handle branches, so it pays to know the details.

Claude Code: claude -w <name>

cd ~/work/proj
claude -w api              # create a worktree and start the session in it
claude -w api --tmux       # also create a tmux session

What actually gets created:

• Path: <repo>/.claude/worktrees/<name>
• Branch: worktree-<name> (branched from the current HEAD)
• The worktree is locked while the session uses it (git worktree list shows locked).

Because the worktree lives inside the repository, git status in your main checkout shows ?? .claude/. Add it to .gitignore:

.claude/worktrees/

Codex: codex --worktree

cd ~/work/proj
codex --worktree                              # interactive
codex exec --worktree "Fix typos in README"   # non-interactive

• Path: ~/.codex/worktrees/<id>/<repo> (outside the repository)
• Branch: none (detached HEAD)

A Codex worktree starts without a branch. Create one before you want to keep the work:

cd ~/.codex/worktrees/<id>/proj
git switch -c codex/ui-polish

4. The biggest problem: commit failures in the Codex sandbox

Under Codex's default sandbox (workspace-write), committing inside a worktree fails like this:

fatal: Unable to create '/home/me/work/proj/.git/worktrees/proj/index.lock': Read-only file system

The cause is how worktrees are built. Inside a worktree, .git is not a directory but a file pointing to .git/worktrees/<name> in the original repository. Git metadata such as the index and HEAD is written there, and the Codex sandbox keeps that path read-only. We confirmed that adding --add-dir <repo>/.git as a writable root does not help: .git stays protected and creating HEAD.lock still fails.

You have three practical options:

1. Let Codex edit code and commit yourself (recommended). It doubles as a review step.
2. In interactive mode, when Codex asks to run a command outside the sandbox, approve it for git commands only.
3. --sandbox danger-full-access — only when the outer environment (container, VM) is already isolated.

Claude Code uses a permission-prompt model rather than this sandbox by default, so committing inside its worktree works normally.

5. What each worktree needs on its own

A worktree checks out only files tracked by git. Anything in .gitignore is missing from a new worktree. For a Node.js project, take care of the following.

Secrets such as .env — Claude Code copies gitignored files listed in a .worktreeinclude file at the repository root into each new worktree:

# .worktreeinclude
.env
.env.local

Codex worktrees have no equivalent, so copy the file yourself:

cp ~/work/proj/.env ~/.codex/worktrees/<id>/proj/

Dependencies — run npm ci in each worktree. Symlinking the main checkout's node_modules leads to confusing errors once branches diverge in their lock files.

Dev server ports — if both agents start a dev server, the ports collide:

PORT=3001 npm run dev   # Claude worktree
PORT=3002 npm run dev   # Codex worktree

Note the port in the agent instruction file (CLAUDE.md, AGENTS.md), e.g. "this worktree uses port 3001", and the agent will stick to it.

Build caches — .next, dist, target and similar outputs exist separately in each worktree. They take more disk than you'd expect, so remove finished worktrees promptly.

6. Splitting work to avoid conflicts

A worktree only prevents file clashes while the agents are working. If two branches change the same part of the same file, you still get a conflict at merge time. How you split the work is what matters.

Split by directory or module. Splitting by feature makes it easy for both agents to touch the same shared utilities or type files.

Give shared files a single owner. Files that conflict often — package.json, lock files, routing and config files — should belong to one side. If the other agent needs a dependency, have it leave a note and add it yourself.

Keep one rules file. Codex reads AGENTS.md; Claude Code reads CLAUDE.md. Put shared rules in AGENTS.md and simply import it from CLAUDE.md so both agents follow the same rules:

<!-- CLAUDE.md -->
@AGENTS.md

State the scope in each task. Something like "Add pagination to the search API. Only modify src/app/api/search/** and src/lib/search/**; if you need to change anything else, don't — tell me instead" sharply reduces boundary violations.

7. Integration: cross-review → conflict pre-check → merge

Cross-review. Having one model review another model's code surfaces issues the same model tends to miss when checking its own work.

# Review Claude's branch with Codex
cd ~/work/proj/.claude/worktrees/api && codex review --base main
 
# Review Codex's branch with Claude (before committing, codex review --uncommitted also works)
cd ~/.codex/worktrees/<id>/proj && claude "Review this branch's changes against main"

Conflict pre-check. You can find out whether a merge would conflict without actually merging (git 2.38+):

git merge-tree --write-tree main worktree-api    && echo "no conflicts"
git merge-tree --write-tree main codex/ui-polish && echo "no conflicts"

A non-zero exit code means there are conflicts, and the output lists the conflicting files.

Merge order. Merge the smallest, first-finished branch into main first. Rebase the remaining branches with git rebase main, rerun the tests, then merge. If conflicts need resolving, hand them to the agent that wrote the branch — it still has the context and is faster.

8. Cleaning up

git worktree list
 
# Codex worktree
git worktree remove ~/.codex/worktrees/<id>/proj
 
# Claude worktree: remove is refused while the session lock remains
git worktree remove .claude/worktrees/api
# fatal: cannot remove a locked working tree, lock reason: claude session api (pid …)
git worktree unlock .claude/worktrees/api
git worktree remove .claude/worktrees/api
 
git branch -d worktree-api      # delete the merged branch
git worktree prune              # clean metadata if you deleted a directory by hand

If a Claude session exits abnormally, the lock can be left behind. The lock reason includes the pid, so confirm that process is no longer running before you unlock.

9. A practical layout: one tmux screen

Worktrees pair well with keeping Claude Code and Codex sessions alive with tmux. Put one agent per window and both keep working even if SSH drops:

cd ~/work/proj
tmux new -d -s dev -n claude 'claude -w api'
tmux new-window -t dev -n codex 'codex --worktree'
tmux new-window -t dev -n main            # your window for review and merging
tmux attach -t dev

Checklist

• Add .claude/worktrees/ to .gitignore
• List .env in .worktreeinclude (copy it by hand for Codex worktrees)
• Run npm ci and use a separate dev server port in each worktree
• In a Codex worktree, create a branch with git switch -c first, and commit yourself
• Split ownership by directory; give shared files (package.json, lock files) one owner
• Put shared rules in AGENTS.md; have CLAUDE.md import @AGENTS.md
• Cross-review → git merge-tree → merge the smallest branch first
• Finished worktrees: unlock → remove → branch -d

Worktrees let your agents run concurrently; finishing without conflicts still comes down to how you split the work and the order you merge it. In a follow-up post we'll extend this approach to teams where several people each work with their own Claude and Codex.