Claude Code with git worktrees: run parallel sessions safely
One folder and one branch per session: start, merge and clean up.
Two Claude Code sessions in the same folder edit the same files. One rewrites a function while the other runs the tests against it, and neither knows. The fix is old and built into git: a worktree is a second working folder of the same repository, on its own branch. This guide shows how to start Claude Code in one, how to run several side by side, and what to clean up afterwards.
Why a worktree and not a second clone
A worktree shares the repository's history and objects with the original, so it costs almost no disk space and appears instantly. Each worktree has its own checked-out branch, its own working files and its own staging area. Two sessions in two worktrees cannot overwrite each other's edits, and their changes meet only when you merge the branches.
Start Claude Code in a worktree
Claude Code has a flag for this. In version 2.1.330, claude --help describes -w, --worktree [name] as "Create a git worktree for this session (optionally named)". Run it inside a git repository:
cd ~/myproject
claude --worktree fix-login
In a test repository the result was a new folder .claude/worktrees/fix-login inside the project and a new branch called worktree-fix-login, both created from the commit you were on. The session works in that folder, so your main checkout stays untouched. Without a name, Claude Code picks one.
Add .claude/worktrees/ to .gitignore. Otherwise git status in the main checkout lists the folder as untracked, which is how it showed up in the test.
Run several sessions in parallel
Open one terminal per task and give each its own name:
claude --worktree fix-login
claude --worktree add-export-csv
claude --worktree update-docs
Each session gets its own branch. When a task is done, review and merge that branch like any other, for example git merge worktree-fix-login from the main checkout, or push it and open a pull request. On a server, combine this with --tmux, which the help describes as "Create a tmux session for the worktree" and says requires --worktree. The tmux guide covers reattaching after a dropped connection.
Do it with plain git instead
Nothing here is specific to Claude Code. You can create the worktree yourself and start Claude Code inside it:
git worktree add -b feat-export ../myproject-export
cd ../myproject-export
claude
This gives you the folder location and the branch name you want. Useful commands:
git worktree listshows every worktree, its commit and its branch.git worktree remove <path>deletes a clean worktree folder.git worktree pruneforgets entries whose folder you deleted by hand.
What a worktree does not share
- Untracked and ignored files. A new worktree contains only what git tracks. Your
.env, anode_modulesfolder or a virtual environment are not copied. Install dependencies and recreate local config in each worktree, or the first test run fails for a reason that has nothing to do with the code. - Branches. Git refuses to check out one branch in two worktrees. Trying
git worktree add ../x masterwhilemasteris checked out fails with "'master' is already used by worktree". That is a feature: it stops two sessions from committing to the same branch. - Ports, databases and other services. Two sessions that both start a dev server on port 3000 or both write to one local database still collide. Give each worktree its own port and its own database name.
- Merge conflicts. Isolation postpones the clash to merge time. Hand out tasks that touch different files, and merge the small ones first.
Clean up
Finished worktrees pile up. The help for claude rm says it deletes a session's worktree while the conversation is kept, so claude --resume still lists it. For the git side, remove the folder and then the branch once it is merged:
git worktree remove .claude/worktrees/fix-login
git branch -d worktree-fix-login
A worktree left behind by a finished claude -p run was listed as locked in the test, with a lock reason naming the session and a process id that no longer existed. git worktree remove refuses a locked worktree. After you have checked that the process is gone, run git worktree unlock <path> first. git branch -d refuses a branch that is not merged, which is the safety you want. Do not reach for -D before you have looked at what is on it.
A short checklist
- One task, one worktree, one branch, one session.
- Name worktrees after the task so
git worktree listreads like a to-do list. - Ignore
.claude/worktrees/in git. - Recreate
.envand dependencies in every new worktree. - Give parallel dev servers different ports and databases.
- Merge, then remove the worktree and delete the merged branch.