Run two Claude Code sessions in one repo with worktrees

Claude Code ships a native worktree flag. Run claude -w refactor in one terminal and claude -w feature in another, and each session gets its own working directory under .claude/worktrees/, its own branch, and its own files. They share the repo's git history but never touch each other's edits, so a refactor and a feature can run in parallel without merge conflicts.

You need two things first. Claude Code installed in a git repository, and git 2.5 or newer, which is when git worktree landed. That covers any install from the last decade.

What a git worktree is

A worktree is a second working directory attached to the same repository. It shares the one .git object store with your main checkout, so there is no copy of the repo and no second clone to keep in sync.

The main checkout has one branch checked out at a time. That is the constraint a worktree removes. With git worktree add ../feature feature-branch, you get a separate folder on disk with feature-branch checked out, while your main folder stays on main. Two branches, two sets of files, one history.

This fits parallel agents well. Two Claude Code sessions in the same folder would fight over the same files. Each one's edits would land on top of the other's, and the working tree would end up in a state neither session expected. Give each session its own worktree and that problem disappears, because each has its own file state.

Start a session with the -w flag

Claude Code does the git worktree add for you. Pass -w with a name and Claude creates the worktree, the branch, and starts the session in it.

claude -w refactor

That command makes a worktree under .claude/worktrees/refactor/ on a new branch named worktree-refactor. The long form is --worktree if you prefer it spelled out. Omit the name and Claude generates one for you, something like bright-running-fox.

claude --worktree

The session opens already inside the worktree directory. Everything Claude reads or writes from here stays in that folder and on that branch.

Run the refactor and the feature at once

Open a second terminal and start the other task with its own name.

# Terminal 1
claude -w refactor
 
# Terminal 2
claude -w feature-auth

Now claude -w feature-auth is running in .claude/worktrees/feature-auth/ on branch worktree-feature-auth. The two sessions read and write different files on different branches. Tell the first to restructure your module layout and the second to add a login flow, and neither one sees the other's half-finished changes.

Run git worktree list from anywhere in the repo to see what is active.

git worktree list

/Users/you/project                     a1b2c3d [main]
/Users/you/project/.claude/worktrees/refactor      e4f5g6h [worktree-refactor]
/Users/you/project/.claude/worktrees/feature-auth  i7j8k9l [worktree-feature-auth]

Add the gitignore line before you commit

Worktree folders live inside your repo, so git sees them as untracked files. Add one line to .gitignore so they stay out of your commits and your git status.

.claude/worktrees/

Do this before the first commit in either session. Without it, the worktree directories show up as untracked content and clutter every diff. The branches still track normally, since the branch data lives in the shared .git store, not in the ignored folder.

Merge both branches back

When a session's work is done, you merge its branch like any other branch. Switch to your main checkout, then merge.

git switch main
git merge worktree-refactor
git merge worktree-feature-auth

If the two tasks stayed independent, both merges apply cleanly. The whole point of splitting them was to keep their file sets apart, so there is nothing to reconcile. If you get a conflict here, it means the refactor and the feature touched the same lines, which is the case where worktrees buy you the least.

Clean up when you are done

A merged worktree is dead weight. Remove the directory and prune the branch.

git worktree remove .claude/worktrees/refactor
git branch -d worktree-refactor

git worktree remove deletes the folder and drops the worktree registration. git branch -d then removes the merged branch. Run git worktree list again and the entry is gone. If a worktree has uncommitted changes, remove refuses unless you pass --force, which protects you from throwing away work by accident.

Pin a subagent to its own worktree

The same isolation works for custom subagents. Add one line to a subagent's frontmatter and every run of that agent gets its own worktree.

---
name: test-writer
isolation: worktree
---

With isolation: worktree set, the subagent works in a fresh worktree each time instead of your live checkout. You can also ask Claude to "use worktrees for your agents" in a session to get the same behavior without editing files. Where the isolation rule lives is a CLAUDE.md decision, covered in how to write a CLAUDE.md.

The setup earns its keep only when the two tasks are separate. Point both sessions at the same files and the merge conflict you dodged comes right back at the end.