Claude Code worktrees: run parallel sessions with git worktrees

To run parallel Claude Code sessions, start each one in its own git worktree with claude --worktree <name> (or -w). Claude Code creates the worktree under .claude/worktrees/<name>/ on a new branch called worktree-<name>, so one session can build a feature while another fixes a bug without their edits colliding.

This guide covers starting sessions, setting up each worktree, cleanup, resuming, subagent isolation and the settings that change how worktrees are created. Everything is based on the official worktrees documentation and the CLI reference.

What is a git worktree and why use one with Claude Code?

A git worktree is a separate working directory with its own files and branch that shares the same repository history and remote as your main checkout. Commits you make in one are visible to the others, but the files on disk are independent.

That independence is what makes parallel agent work safe. Two Claude Code sessions in the same folder edit the same files and trip over each other. Two sessions in two worktrees each have their own copy to change, test and commit.

Worktrees are one of several ways to run Claude in parallel:

How do you start Claude Code in a worktree?

Pass --worktree with a name:

claude --worktree feature-auth

In a second terminal, start another isolated session:

claude --worktree bugfix-123

Things to know about starting:

• The name is optional. Leave it out and Claude Code generates one, such as bright-running-fox.
• Trust comes first. Interactive runs need workspace trust. If you have never run Claude in the repository, run claude there once and accept the trust dialog, or --worktree exits with an error. Runs with -p skip that check.
• Ignore the folder. Add .claude/worktrees/ to your .gitignore so worktree files don't appear as untracked changes in the main checkout.
• Use tmux if you like panes. claude -w feature-auth --tmux creates a tmux session for the worktree. It uses iTerm2 native panes when available; --tmux=classic forces traditional tmux.
• Branch from a pull request. Pass a PR number, a GitHub pull request URL or a GitLab merge request URL. Quote the number so your shell doesn't treat # as a comment:

claude --worktree "#1234"

Claude Code fetches that change from origin and creates the worktree at .claude/worktrees/pr-1234.

You can also ask for a worktree mid-session. Say "work in a worktree" and Claude creates one with its EnterWorktree tool. If Claude wants to enter a path outside .claude/worktrees/, Claude Code asks you first, because the move takes the session's write access and project configuration with it.

How do you set up the environment in each worktree?

A worktree is a fresh checkout. Gitignored files such as .env and installed dependencies such as node_modules are not there.

Copy secrets and local config with .worktreeinclude. Add this file to your project root using .gitignore syntax. Claude Code copies files that match a pattern and are also gitignored into every worktree it creates, including subagent worktrees:

.env
.env.local
config/secrets.json

Install dependencies or share them. Either ask Claude to install dependencies in the new worktree, or symlink large directories from the main checkout with the worktree.symlinkDirectories setting:

{
  "worktree": {
    "symlinkDirectories": ["node_modules", ".cache"]
  }
}

According to the settings reference, this keeps large directories from being duplicated on disk: each listed directory in the worktree is a symlink back to the main checkout's copy.

How does worktree cleanup work?

When you exit an interactive worktree session, Claude Code checks for work that removal would delete:

• Clean worktree: for an unnamed session, Claude Code removes the worktree and its branch automatically. A named session asks first.
• Changes or new commits: Claude Code asks whether to keep or remove it. Keeping preserves the folder and branch, and Claude Code prints a claude --worktree <name> --resume command to come back later. Removing deletes the folder, the branch and the work in them.
• State it can't verify: Claude Code asks rather than removing anything.

Runs with -p have no exit prompt, so their worktrees stay on disk. Remove them yourself:

git worktree list
git worktree remove .claude/worktrees/feature-auth

If git refuses because the worktree is locked, run git worktree unlock on it first. Add --force to git worktree remove if it has uncommitted changes you are sure you don't need.

Worktrees that Claude Code created for subagents and background sessions are removed by a periodic sweep once they are older than your cleanupPeriodDays setting (30 days by default), as long as they hold no uncommitted work or unpushed commits. The sweep never touches worktrees you created yourself with git worktree add.

How do you resume or reuse a worktree session?

If a session ended inside a worktree without exiting it, --resume or --continue returns the session to that worktree. Start from the main checkout and Claude Code finds it. If the worktree folder has since been deleted, the session resumes in the directory you launched from and tells you the worktree is gone.

Passing --worktree a name that already exists opens that worktree instead of creating a new one. With the default base, a reopened worktree that has no changes and no commits of its own (or whose pull request was merged and remote branch deleted) resets to the default branch. Otherwise it reopens where you left off.

How do you customize worktree creation?

The defaults suit most projects: worktrees go under .claude/worktrees/, branch from the default branch, and check out tracked files only. The worktree block in your Claude Code settings changes that, as the settings reference documents:

{
  "worktree": {
    "baseRef": "head",
    "sparsePaths": ["packages/my-app", "shared/utils"]
  }
}

You can't set baseRef to a branch name. To start from a specific existing branch, or to place a worktree outside the repository, create it with git and start Claude inside it:

git worktree add ../project-bugfix fix-issue-456
cd ../project-bugfix
claude

To replace git entirely, for SVN, Perforce or Mercurial, configure WorktreeCreate and WorktreeRemove hooks. The hook then owns creation, and .worktreeinclude is not processed, so copy local files inside the hook script.

How do subagents use worktrees?

Subagents can each get their own worktree so parallel edits don't conflict. Ask Claude to "use worktrees for your agents," or make it permanent for a custom subagent with isolation: worktree in its frontmatter:

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

Apply the requested refactor across every affected file, then run the tests
and report the results.

Each subagent gets a temporary worktree that Claude Code removes when the subagent finishes without changes. Subagent worktrees use the same baseRef as --worktree, so set it to "head" if subagents need your in-progress work.

What do worktrees share with the main checkout?

A worktree has its own files and branch but shares:

• The .git directory. Commits made in a worktree land in the same repository, and the sandbox allows those writes so git commit works with sandboxing on.
• Project-scope plugins installed from the main checkout.
• Permission approvals. "Yes, and don't ask again" in a worktree saves the rule to the main checkout's .claude/settings.local.json, so it applies everywhere in the repository and survives the worktree's removal. See the permissions guide for how those rules work.
• Untracked skills, agents and commands. If the worktree has no .claude/skills folder, for example because yours is gitignored, Claude Code loads the main checkout's project skills.

Tips for working with worktrees

• Give each session one clear task and its own descriptive name, so branches and folders are easy to tell apart later.
• Know what isolation covers. While a session is in a worktree, Claude Code blocks file edits that target the main checkout and git commands redirected into it. It does not track every file a shell command writes, so a cp into the main checkout isn't refused by those checks.
• Hook paths stay put. ${CLAUDE_PROJECT_DIR} in hooks still points at the project root where the session started. A hook that needs the worktree path should read the cwd field from its input.
• Merge like any branch. Each worktree is a normal git branch, so review, push and open a pull request from it as usual.

Keep the prompts you reuse across sessions

Parallel sessions work best when every session gets the same well-written instructions. Kipt keeps your prompts and Agent Skills as Markdown in a private GitHub repo you own, with {{name}} blanks you fill in per task, and installs every skill into Claude Code with one npx skills add command.