Parallel Claude Code sessions with git worktrees

Who this is for and what you will be able to do

This guide is for developers who want two or three Claude Code sessions working on one repository at the same time without their file edits colliding. By the end you will be able to open an isolated session with one flag, clean up afterward, and know where the isolation stops.

What a worktree is and how it fits with parallel sessions

A git worktree is a second working directory for the same repository. It has its own files and its own branch, but it shares history and the remote with the main checkout^[1]. If each Claude Code session gets its own worktree, each one edits its own copy of the files. One session can build a feature while another fixes a bug, and the two sets of changes stay in separate directories^[1].

What to prepare

• A git repository. Worktrees are a git feature, so the project has to be one.
• Workspace trust. In an interactive run, if you have not used Claude in this directory before, run claude there once to accept the trust dialog. Otherwise --worktree exits with an error. Non-interactive runs with -p skip this check^[1].
• A .gitignore entry. The docs suggest adding .claude/worktrees/ so worktree contents do not show up as untracked files in the main checkout^[1].
• Dependencies in every worktree. A worktree is a fresh checkout, so the environment has to be set up inside it^[1].

Start two isolated sessions

1. From the repository root, run the command with a name:

claude --worktree feature-auth

1. Claude creates a worktree under .claude/worktrees/feature-auth/ on a new branch called worktree-feature-auth, then starts there^[1].
2. In a second terminal, run the command again with a different name. That session is isolated from the first^[1].

If you leave out the name, Claude generates one, such as bright-running-fox^[1].

Getting untracked files into a new worktree

A new worktree lacks gitignored files such as .env. To copy them in, put a .worktreeinclude file in the project root. It uses .gitignore syntax, and Claude copies the matching files when it creates the worktree^[1]. Only files that match a pattern and are also gitignored get copied, so tracked files are never duplicated^[1]. Here is an example that copies two env files and a secrets config:

.env
.env.local
config/secrets.json

Moving between worktrees inside a session

Ask Claude to work in a worktree and it can create one with the EnterWorktree tool. It can also switch to another worktree under .claude/worktrees/ when given that path^[1]. A path outside that folder needs your approval. Neither an EnterWorktree rule nor choosing "don't ask again" skips the prompt; only bypassPermissions mode does^[1].

Hooks need care here. After entering a worktree, ${CLAUDE_PROJECT_DIR} still points at the project root where the session started. To find the worktree, read the cwd field of the hook input^[1].

How isolation is enforced

While a session is isolated, Claude Code blocks:

• Edit, Write, and NotebookEdit calls that target the main checkout;
• Bash, PowerShell, and Monitor commands whose working directory resolves to the main checkout;
• git commands that point into the main checkout through git -C, --git-dir, GIT_DIR, GIT_WORK_TREE, or a cd into the main checkout first^[1].

Subagents in their own worktrees

Subagents can run in separate worktrees so that parallel edits do not conflict. Add isolation: worktree to a custom subagent's frontmatter in .claude/agents/ to make it always run that way^[1]:

---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---

A subagent's worktree is deleted automatically when the subagent finishes without changes. If it has changes, it stays until the periodic sweep can remove it safely^[1]. The sweep deletes subagent and background-session worktrees older than cleanupPeriodDays, but keeps any that still have changed or untracked files or unpushed commits^[1].

Cleaning up when you exit

When an interactive worktree session ends, Claude checks for work that removal would destroy. An unnamed session with a clean worktree gets it removed automatically; a named session is asked first^[1]. If there is work in it, Claude asks whether to keep or remove it. Keeping preserves the directory and branch, and the exit message prints claude --worktree <name> --resume so you can return later^[1].

To remove a worktree by hand, run git worktree remove. Add --force if it has uncommitted or untracked files, and run git worktree unlock first if git reports a lock^[1].

Creating worktrees with git directly

You can skip the flag and create the worktree with git yourself, then start Claude inside it:

git worktree add ../project-feature-a -b feature-a
cd ../project-feature-a
claude

This creates the worktree on a new branch^[1].

Base branch and pull requests

By default a new worktree branches from the repository's default branch. Setting worktree.baseRef to "head" branches from your current local HEAD instead, so unpushed commits come along^[1].

To start from a pull request, add # and its number after --worktree, for example claude --worktree "#1234". Quote the argument so the shell does not treat # as a comment. Claude fetches that pull request's head commit from origin and creates the worktree at .claude/worktrees/pr-<number>^[1].

Limits and common problems

• **index.lock errors.** By default, git commands fail with an index.lock error if you run claude in a subdirectory of a worktree. With the sandbox enabled, commands such as git commit work from the worktree root^[1].
• Shared state. A worktree shares the main checkout's .git directory, project-scope plugins, and permission approvals. A "Yes, and don't ask again" rule chosen inside a worktree is saved to the main checkout's .claude/settings.local.json^[1].
• Git LFS. If LFS was set up with git lfs install --local, a worktree Claude creates holds pointer files instead of the real content. Run git lfs pull inside the worktree to fetch it^[1].

Next steps

The official documentation covers subagent isolation and the remaining worktree details^[1].