Git worktree and Codex

Git worktree was introduced many years ago, and it has now become widely used with AI agents.

With git worktree, you can create separate workspaces for AI agents, each with its own changes and branches, so they can work independently.

Let’s cover first the basics about git worktree, then check how to work with it with different AI Agents.

Basic notions

Create and list a worktree

A worktree can be created with or without a separate branch. I am going to use this repo as an example (Repo link).

Initially, I only have one worktree, which is attached to the HEAD of the main branch:

> git worktree list
/Users/jiahaoliu/projects/github/gitWorktree 6fa05f6 [main]

> git log
commit 6fa05f6c2f5f8d5b241654b943e873bd752f9d05 (HEAD -> main, origin/main, origin/HEAD)
Author: Jiahao Liu Liu 
Date:   Wed May 20 15:01:01 2026 +0200

    First version of the app

commit 57fba84aaae768c90faa94c83ee0f1e3ca82b342
Author: Jiahao Liu Liu
Date:   Wed May 20 14:38:10 2026 +0200

    Initial commit

Note there are three pieces of information here:

/Users/jiahaoliu/projects/github/gitWorktree 6fa05f6 [main]

• The first field is the location of the folder
• The second one is the commit which it points to
• The third one is the branch name

The basic way to create a worktree is using this command:

git worktree add -b myBranch ../myFolder main

So this will create a new branch called myBranch , in the ../myFolder folder, and it will be created from the main branch.

Now, if I list the worktree, I will see the following

> git worktree list
/Users/jiahaoliu/projects/github/gitWorktree 6fa05f6 [main]
/Users/jiahaoliu/projects/github/myFolder    6fa05f6 [myBranch]

At the same time, the branch created is visible to all worktrees, meaning if I create another branch from another worktree, it will be seen by all the worktrees.

> git worktree add -b myBranch2 ../myFolder2 main
Preparing worktree (new branch 'myBranch2')
HEAD is now at 6fa05f6 First version of the app

> git worktree list
/Users/jiahaoliu/projects/github/gitWorktree 6fa05f6 [main]
/Users/jiahaoliu/projects/github/myFolder    6fa05f6 [myBranch]
/Users/jiahaoliu/projects/github/myFolder2   6fa05f6 [myBranch2]

> git branch
* main
+ myBranch
+ myBranch2

Now, when a branch is associated with a specific worktree, from another worktree, I cannot switch to that branch.

> git switch myBranch2
fatal: 'myBranch2' is already used by worktree at '/Users/jiahaoliu/projects/github/myFolder2'

Sidenotes

Before showing how to do it, there are two details here:

1. The worktrees have been created outside of the source folder. This is because the new worktree folder contains a workable version of the code and it can create confusion for the current worktree. Some agents, like Codex, will create the worktree under ~/.codex/worktree folder. (Check codex section below). Under .git , there is a worktrees folder, which contains a reference to all the existing worktrees.
2. The add command could be simplified as

> git worktree add .git/worktree/withoutBranch
Preparing worktree (new branch 'withoutBranch')
HEAD is now at 6fa05f6 First version of the app

git worktree list
/Users/jiahaoliu/projects/github/gitWorktree                             6fa05f6 [main]
/Users/jiahaoliu/projects/github/gitWorktree/.git/worktree/myFolder      6fa05f6 [myBranch]
/Users/jiahaoliu/projects/github/gitWorktree/.git/worktree/myFolder2     6fa05f6 [myBranch2]
/Users/jiahaoliu/projects/github/gitWorktree/.git/worktree/withoutBranch 6fa05f6 [withoutBranch]

> git branch
* main
+ myBranch
+ myBranch2
+ withoutBranch

Git will create a branch by default and use the main branch as the starting point.

Switch to another worktree

Once the worktree is created, they are separate folder with workable code. What you have to do is just switch to that branch.

> cd ../myFolder
> git status
On branch myBranch
nothing to commit, working tree clean

> git worktree list
/Users/jiahaoliu/projects/github/gitWorktree 6fa05f6 [main]
/Users/jiahaoliu/projects/github/myFolder    6fa05f6 [myBranch]
/Users/jiahaoliu/projects/github/myFolder2   6fa05f6 [myBranch2]

Remove a worktree

The command to remove a worktree is git worktree remove folderLocation

> git worktree list
/Users/jiahaoliu/projects/github/gitWorktree 6fa05f6 [main]
/Users/jiahaoliu/projects/github/myFolder    6fa05f6 [myBranch]
/Users/jiahaoliu/projects/github/myFolder2   6fa05f6 [myBranch2]

> git worktree remove /Users/jiahaoliu/projects/github/myFolder

> git worktree list
/Users/jiahaoliu/projects/github/gitWorktree 6fa05f6 [main]
/Users/jiahaoliu/projects/github/myFolder2   6fa05f6 [myBranch2]

But if a worktree contains changes that are not committed, git will show an error

> git worktree remove /Users/jiahaoliu/projects/github/myFolder2
fatal: '/Users/jiahaoliu/projects/github/myFolder2' contains modified or untracked files, use --force to delete it

Use the flag --force to remove it forcefully

> git worktree remove /Users/jiahaoliu/projects/github/myFolder2 --force

Note this will only remove the worktree, not the branch that it is associated. Use git branch -D branchName to remove it

> git branch
* main
  myBranch
  myBranch2

> git branch -D myBranch
Deleted branch myBranch (was 6fa05f6).

Codex

Codex will create the worktree under ~/.codex/worktree/ folder

> git worktree list
/Users/jiahaoliu/.codex/worktrees/f389/gitWorktree                       6fa05f6 (detached HEAD)

Note Codex does not create a branch by default, but it rather creates the worktree detached.

This is because the worktree works independently with the branches. When we archive the current chat, the worktree will be removed automatically.

Create a branch for worktree

To create a new branch for the worktree, use the panel on the right:

Optionally you can set a prefix

And commit unstaged changes.

The new branch will be seen from all the worktrees

> git branch
+ LOY/check-current-time
* main

Permanent worktree in Codex

If you want to work on several tasks at the same time, the trick here is to create permanent worktree.

Create a permanent worktree

The new worktree will have the symbol of bifurcation next to the name

This worktree will be listed as a permanent project. From here you can either work locally or create another worktree, which will be organized under the original worktree with a bifurcation symbol.

Permanent worktree with local works

Original worktree with another worktree

> git worktree list
/Users/jiahaoliu/projects/github/gitWorktree       6fa05f6 [main]
/Users/jiahaoliu/.codex/worktrees/6d0f/gitWorktree 6fa05f6 (detached HEAD)
/Users/jiahaoliu/.codex/worktrees/ff11/gitWorktree 6fa05f6 (detached HEAD)

Here are three worktrees

1. The original worktree
2. The permanent worktree
3. The worktree under the original worktree

Branches handoff

You can also handoff the content from one worktree to another worktree in form of branch.

worktree handoff

Hand off branch

The new branch will be created under the new worktree with all the changes

> git branch
  Codex/locate-worktree
* Codex/worktree2

Reference

• Net Ninja — Git Worktrees Tutorial
• Git-scm — Git worktrees
• Domen Lanišnik — Increase Productivity with Git Worktrees as an Android Developer