How do I run two Claude Code sessions on the same repo at once?

When you run two claude sessions in the same directory, they share the working tree. One session’s uncommitted changes are visible to the other. A half-written edit blocks the second session’s reads. Worktrees solve this by giving each session its own checked-out branch.

Start a session in a worktree

claude --worktree api-refactor

Claude Code creates .claude/worktrees/api-refactor/ as a git worktree, checks out a new branch called api-refactor branched from origin/HEAD, and starts the session inside it. Your main working tree is unchanged.

Run a second session at the same time in a different worktree:

claude --worktree auth-fix

Two sessions, two branches, no interference.

Name and base ref

The name you pass to --worktree becomes both the directory name under .claude/worktrees/ and the branch name. Keep it short and slug-shaped.

By default, the branch is created from origin/HEAD. To branch from your current local HEAD instead:

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

Set this in .claude/settings.json. Useful when you are mid-feature and want a worktree off your working branch rather than main.

Check out a pull request

claude --worktree "#1234"

The # prefix tells Claude Code to check out that PR’s branch into the worktree. The branch is fetched from the remote automatically. Use this for PR review sessions that should not affect your current work.

Include env files that are gitignored

Worktrees share the git history but not untracked files. If your session needs a .env file that is gitignored, list it in .worktreeinclude:

# .worktreeinclude
.env
.env.local
.env.test

Files listed here are symlinked (or copied, depending on OS) into each new worktree. Without this, the new worktree runs without your credentials and the session fails on the first database call.

Automatic cleanup

If a worktree session ends without producing any commits, Claude Code deletes the worktree automatically. The branch is also removed. There is nothing to clean up manually.

If commits were made, the worktree and branch persist. Merge them yourself:

git merge api-refactor
# or
gh pr create --head api-refactor

Use worktrees in subagents

When spawning a subagent that should work in isolation, set isolation: "worktree" in the subagent frontmatter:

---
name: refactor-payments
isolation: worktree
allowed-tools:
  - Read
  - Edit
  - Bash
---

Refactor the payments module to use the new retry library.

The subagent gets its own worktree branched from origin/HEAD. If it commits, the branch survives. If not, the worktree is cleaned up when the subagent exits.

Footguns

--worktree requires a git repository. It fails in a directory that is not a git repo. There is no workaround short of git init.

Hooks and settings are shared from the main repo. Hooks that use absolute paths work fine. Hooks that assume the current directory is the repo root may break if they run from inside .claude/worktrees/<name>/.

.worktreeinclude must be committed. If you add it to .gitignore or forget to commit it, new teammates get worktrees without the env file and spend time debugging missing credentials.

Worktree branches are local only until you push. A session that commits to a worktree branch does not push automatically. If the machine dies before you push, the commits exist only in .claude/worktrees/<name>/. Push or create a PR before considering the work safe.

Two sessions on the same worktree name is an error. If a worktree named api-refactor already exists, claude --worktree api-refactor fails. Pick a unique name or clean up the old worktree first with git worktree remove .claude/worktrees/api-refactor.

When NOT to use worktrees

• You want changes from one session to be visible to the other immediately. Worktrees isolate by design. Use a shared directory session if coordination in real time matters.
• You are running Claude Code outside a git repository. Use separate directories and separate terminals.
• The task is short and you are the only user. Starting a session directly in your working tree is simpler for one-off edits.