Two Claude Code sessions in the same folder share one set of files. One session edits a file, the other reads the old version and writes over it, and neither notices. Git worktrees fix this by giving each session its own copy of the repository to edit.
What a worktree is
A git worktree is a second working directory attached to the same repository. It has its own files and its own branch, but it shares the history, the remote and the .git directory with your main checkout. A commit made in one worktree is visible from all of them straight away, with no push or fetch in between.
Each session edits its own files, and the work comes together later through ordinary branches and merges.
Start a session in a worktree
Claude Code has this built in. Pass --worktree (or -w) with a name:
claude --worktree feature-authThis creates a worktree at .claude/worktrees/feature-auth/ in your repository root, on a new branch called worktree-feature-auth, and starts the session inside it. Open a second terminal and run the same command with another name for a second isolated session:
claude --worktree fix-login-bugLeave the name out and Claude Code picks one for you. A few things to know before the first run:
- The repository needs at least one commit, because the worktree branches from an existing commit.
- You need to have run plain
claudein the directory once and accepted the trust prompt, or--worktreeexits with an error. Runs with-pskip the trust check. - Add
.claude/worktrees/to.gitignore, or the worktrees show up as untracked files in your main checkout.
If you live in tmux, the installed CLI (version 2.1.306) also has --tmux, which opens the worktree session in a tmux session of its own. It only works together with --worktree.
You can also ask for a worktree mid-session. Say "work in a worktree" and Claude creates one with its EnterWorktree tool.
Set up the new checkout
A worktree is a fresh checkout of tracked files only. Your node_modules, virtual environments and build output aren't there, so install dependencies first, or ask Claude to.
Gitignored files such as .env are missing too. To copy them in automatically, add a .worktreeinclude file to the project root. It uses .gitignore syntax, and only files that match a pattern and are gitignored get copied:
.env
.env.local
config/secrets.jsonChoose where the branch starts
By default a new worktree branches from your repository's default branch on the remote, usually main. That gives a clean start, but it means unpushed commits on your current branch aren't in it.
To branch from your current local HEAD instead, set worktree.baseRef in settings:
{
"worktree": {
"baseRef": "head"
}
}The setting takes only "fresh" (the default) or "head", not a branch name. To start from an existing branch, create the worktree with git yourself.
Create worktrees with git directly
The manual route is useful when you want a specific branch or a folder outside the repository:
# new branch in a sibling folder
git worktree add ../project-feature-a -b feature-a
# existing branch
git worktree add ../project-bugfix fix-issue-456
cd ../project-feature-a
claudeGit won't check out a branch that is already checked out in another worktree. That rule protects you: two sessions can't end up on the same branch by accident.
List and remove worktrees with:
git worktree list
git worktree remove ../project-feature-agit worktree remove refuses if the worktree has uncommitted changes or untracked files. Add --force only once you're sure nothing in it matters.
Cleaning up
When you exit a --worktree session, Claude Code checks for work that removal would destroy: changed or untracked files, and new commits.
| State on exit | What happens |
|---|---|
| Clean, unnamed session | Worktree and branch removed automatically |
| Clean, named session | You're asked whether to keep it |
| Has changes or commits | You're asked to keep or remove it |
If you keep it, Claude Code prints a claude --worktree <name> --resume command to get back to it later. Runs with -p have no exit prompt, so their worktrees stay until you remove them yourself.
What worktrees don't isolate
A worktree separates files. Several things are still shared:
- The
.gitdirectory, so every ref underrefs/is shared. Branches, tags and the stash are the same in every worktree. - Permission approvals. Choosing "Yes, and don't ask again" in a worktree saves the rule to the main checkout's
.claude/settings.local.json, so it applies in all of them. - Anything outside the repository: databases, ports, caches in your home folder. Two sessions running dev servers on the same port will still clash.
Hooks also need care. Inside a worktree, ${CLAUDE_PROJECT_DIR} still points at the project root where the session started. A hook that needs the worktree's path should read the cwd field from its JSON input instead. The hooks guide covers that input.
How I keep parallel sessions apart
I run many Claude Code sessions at once on the same repositories, across worktrees and separate checkouts. Worktrees stop two sessions writing the same file on disk. They don't stop two sessions working on the same problem in different worktrees and producing conflicting changes.
So my global rules say a session claims the files it expects to touch before its first edit, and a PreToolUse hook on Write, Edit and MultiEdit warns when a file is already claimed by another session. If a file is claimed, the session doesn't edit through it. It asks the other session or waits, and an explicit go-ahead from me is the only thing that overrides a claim. Rules like this live in memory, so every session reads them.
The same rules ban a few git habits that break once sessions share a repository: never git stash, never a blind git commit --amend, and always stage files by explicit path. The stash ban follows straight from the shared refs above. refs/stash is one stack for every worktree, so a session that stashes and pops can pick up another session's changes.
Questions
Do I need worktrees to run two Claude Code sessions at once?
Only if both sessions edit files. Two sessions that only read code, answer questions or review can share one folder safely. Once both write, give each its own worktree.
Can two worktrees use the same branch?
No. Git refuses to check out a branch that another worktree already has checked out, unless you force it. Give each session its own branch and merge them when the work is done.
Why is my .env missing in the worktree?
A worktree only contains tracked files, and .env is usually gitignored. List it in a .worktreeinclude file at the project root and Claude Code copies it into each new worktree it creates.