Git first, agents second

Claude Code worktrees, starting with plain git worktree

Updated November 17, 20269 min read

Claude Code worktrees are built on git worktree, a git command that gives one project a second (or third) working folder, each on its own branch. Learn the git part first and the Claude part is easy: claude --worktree name simply makes one of these folders for you and starts a session inside it. This page covers the git commands, the mistakes people make, the Claude Code flags, and how to bring finished work back into your main branch.

Worktrees in five lines

  • A worktree is an extra folder for the same git repository, on its own branch.
  • Make one with git worktree add ../folder -b branch, see them with git worktree list, delete with git worktree remove.
  • A branch can only be open in one worktree at a time.
  • claude -w name creates .claude/worktrees/name/ on a branch called worktree-name and starts Claude there.
  • Merge the branch back like any other branch, then remove the worktree.

What git worktree gives you

Normally a git repository (a project folder that git tracks) has one working folder, so you can only have one branch open at a time. To switch, you stash or commit your half-done work, change branch, and switch back later. git worktree removes that juggling. It adds more folders that all belong to the same repository.

Git calls your original folder the main worktree and each extra folder a linked worktree. Every linked worktree has its own files, its own open branch and its own staged changes. They all share one history: a commit you make in one folder is visible from all the others straight away, and they all push to the same remote (GitHub, GitLab and so on).

Compared with cloning the project a second time, a worktree is quicker to make, uses less disk space because the history is stored once, and keeps every branch in one repository. That is exactly why AI coding tools use worktrees: two agents can each get a folder of their own without stepping on each other's files.

Rather skip the git commands completely? VibeCodingDeck calls these safe copies. Each agent can work on its own copy of the project (git worktrees under the hood), and you review and merge the good work back with a click.

Git worktree commands with real examples

CommandWhat it does
git worktree add ../app-login -b login-pageNew folder ../app-login on a brand new branch called login-page
git worktree add ../app-fix fix-issue-456New folder on a branch that already exists
git worktree add ../hotfixNo branch given, so git names the branch after the folder (hotfix) and creates it if needed
git worktree add -d ../scratchThrowaway folder with no branch (detached), at the same commit you are on
git worktree listShows every worktree, the commit it is on and its branch
git worktree list --porcelainSame list in a fixed format for scripts
git worktree remove ../app-loginDeletes the folder and its record (only if it has no unsaved changes)
git worktree remove --force ../app-loginDeletes it even with uncommitted or untracked files
git worktree pruneCleans up records for folders you deleted by hand
git worktree lock --reason "on USB drive" ../app-usbStops a worktree being pruned, moved or deleted
git worktree unlock ../app-usbRemoves the lock so the worktree can be pruned, moved or deleted again
git worktree move ../app-login ../loginMoves a worktree to a new path
git worktree repairReconnects worktrees after you moved the main folder

Here is a full git worktree add session from start to finish, the way you would do it by hand before handing the folder to Claude Code:

# from inside your main project folder
git worktree add ../myapp-login -b login-page

git worktree list
# /home/you/myapp         a1b2c3d [main]
# /home/you/myapp-login   a1b2c3d [login-page]

cd ../myapp-login
npm install      # a new worktree has no installed packages yet
claude           # start Claude Code in this folder

The two folders start at the same commit. From now on, anything you do in myapp-login happens on the login-page branch, while myapp stays on main exactly as you left it.

Common git worktree mistakes and their fixes

The branch is already open in another worktree

Git refuses to open one branch in two worktrees at the same time, because two folders changing the same branch would confuse it. Give each worktree its own branch with -b new-name. If you really need the same commit twice, use -d for a detached copy instead.

You deleted the folder in File Explorer or Finder

Deleting the folder by hand leaves git's record of it behind, and git worktree list keeps showing it. Run git worktree prune to tidy that up. Next time, use git worktree remove so the folder and the record go together.

git worktree remove refuses to delete the folder

Git only removes clean worktrees, meaning no changed files and no untracked files. Commit or copy anything you want to keep, then add --force. If the worktree is locked, run git worktree unlock ../app-usb first, or give --force twice: git worktree remove -f -f ../app-usb.

Your .env file and node_modules are missing

A worktree holds only the files git tracks. Anything in .gitignore, like .env secrets files and installed packages, is not there. Copy the small files in, run your install command in the new folder, and see the .worktreeinclude trick further down if you use Claude Code.

Two dev servers fight over one port

Each worktree is a full copy of your app. If you start the dev server in two of them, the second one fails or quietly picks another port. Give each worktree its own port number so you always know which copy you are looking at.

You moved the main project folder

Linked worktrees remember where the main folder lives. After a move they lose track of it. Run git worktree repair from the main folder to reconnect them.

Worktree folders show up as untracked files

If you place worktrees inside your project, the main folder sees them as new files. Either put them next to the project (like ../myapp-login), or add their folder to .gitignore.

How Claude Code uses git worktree

Claude Code wraps all of the above into one flag. claude --worktree (short form -w) creates the worktree, makes the branch and starts a session inside it:

claude --worktree feature-auth     # or: claude -w feature-auth
claude -w                          # no name: Claude makes one up, like bright-running-fox
claude --worktree "#1234"          # branch from pull request 1234 (keep the quotes)
claude -w feature-auth --tmux      # also open a tmux session for it
  • The folder is .claude/worktrees/feature-auth/ at the root of your repository, on a new branch called worktree-feature-auth.
  • Run the same command with a different name in a second terminal for a second isolated session.
  • Using a name that already exists reopens that worktree instead of making a new one.
  • A pull request number or URL creates .claude/worktrees/pr-1234. The quotes stop your shell from treating # as the start of a comment.
  • Your repository needs at least one commit first. In a folder Claude Code has never opened, run claude once to accept the trust prompt.
  • Mid-session, you can also just say "work in a worktree" and Claude creates one.
  • While a session is inside a worktree, Claude Code blocks its file edits and git commands from reaching your main folder.

Tip

Add .claude/worktrees/ to your .gitignore, so the worktree folders do not appear as untracked files in your main checkout.

Bring your .env along with .worktreeinclude

Create a file called .worktreeinclude in your project root. It uses the same pattern rules as .gitignore. Any file that matches a line and is also gitignored gets copied into every worktree Claude Code makes, including subagent worktrees:

.env
.env.local
config/secrets.json

Keep it to small files, because they are copied, not linked. For big folders like node_modules, put your install command in CLAUDE.md so Claude runs it whenever it starts in a fresh worktree.

Choose where new worktrees branch from

By default ("fresh"), new worktrees start from your repository's default branch on the remote, usually main. To start from your current local work instead, including commits you have not pushed, set this in your settings file:

{
  "worktree": {
    "baseRef": "head"
  }
}

Worktrees for subagents and big batch jobs

Add isolation: worktree to a custom subagent and it always works in its own temporary worktree, which Claude Code removes if the agent finishes without changes. For one huge mechanical change, the built-in /batch command splits the work into 5 to 30 pieces, shows you the plan, and once you approve gives each piece its own worktree.

Merging worktree work back into main

A worktree branch is a normal git branch. You merge it the same way you would merge any other. Here is the full path for a Claude Code session called feature-auth:

  1. 1

    Commit inside the worktree

    Ask Claude to commit its work, or run git add and git commit yourself in .claude/worktrees/feature-auth/. Uncommitted changes cannot be merged.

  2. 2

    Look at what changed

    From your main folder, run git diff main...worktree-feature-auth to see everything the branch adds. This is the moment to run your tests or a code review.

  3. 3

    Merge, or open a pull request

    On main in your main folder, run git merge worktree-feature-auth. If you work with pull requests, push the branch with git push -u origin worktree-feature-auth and open one instead.

  4. 4

    Sort out any conflicts

    If two worktrees changed the same lines, git stops and marks the clash in the file. Fix those lines, then git add and git commit. You can ask Claude to help resolve them.

  5. 5

    Clean up

    Remove the folder with git worktree remove .claude/worktrees/feature-auth, then delete the merged branch with git branch -d worktree-feature-auth.

cd ~/myapp                                   # your main folder, on main
git diff main...worktree-feature-auth        # review
git merge worktree-feature-auth              # bring it in
git worktree remove .claude/worktrees/feature-auth
git branch -d worktree-feature-auth

What Claude Code does with a worktree when you exit

You often do not need the cleanup step above, because Claude Code checks the worktree when you leave the session:

  • Nothing changed, unnamed session: Claude Code removes the worktree and its branch for you.
  • Nothing changed, named session: it asks first, in case you want to keep it.
  • There is work in it: it asks whether to keep or remove it. Keeping it prints a claude --worktree <name> --resume command so you can carry on later.
  • Runs started with `claude -p`: there is no exit prompt, so nothing is cleaned up. Remove those with git worktree remove yourself. Claude Code leaves its lock on them, so if git refuses, run git worktree unlock on the folder first.
  • Subagent and background worktrees are cleared out later, once they are older than your cleanupPeriodDays setting. A sweep skips any that still hold changed files or unpushed commits, so you never lose work this way.

If you run lots of these in parallel, you will want to see them all at once. The Claude Code tmux page covers one way to lay out terminals, and running multiple Claude Code agents covers a grid with a status light per session.

Worktree questions people search

What is the difference between git worktree and git clone?

+

A clone is a whole second repository with its own copy of the history. A worktree is an extra folder attached to the same repository, so it is quicker to make, uses less disk space, and commits show up in every worktree straight away.

Where does Claude Code put worktrees?

+

In .claude/worktrees/<name>/ at your repository root, on a branch named worktree-<name>. A worktree made from a pull request goes in .claude/worktrees/pr-<number>.

How do I delete a git worktree?

+

Run git worktree remove <path>. Add --force if it has uncommitted changes. If it is locked, run git worktree unlock <path> first. If you already deleted the folder by hand, run git worktree prune.

Can two worktrees use the same branch?

+

No. Git allows a branch to be open in only one worktree at a time. Make a new branch for each worktree with -b, or use -d for a detached copy.

How do I see all my git worktrees?

+

Run git worktree list. It shows each folder, the commit it is on, its branch, and whether it is locked or can be pruned. Add --porcelain for script-friendly output.

Does every worktree need its own npm install?

+

Yes. A worktree only contains tracked files, so packages and .env files are missing. Run your install command in each new worktree, and list small gitignored files in .worktreeinclude so Claude Code copies them for you.

Sources

Run up to 12 AI coding agents in one window.

Claude Code, Codex, Gemini, Grok and more, side by side. Windows and Mac. From $29 a month.

Get started

Keep reading