Run Claude Code sessions in parallel with git worktrees

Two Claude Code sessions editing the same folder will trip over each other. A git worktree fixes that: it is a separate working directory with its own files and its own branch, sharing the same repository history and remote. Run each session in its own worktree and one can build a feature while another fixes a bug.

Start a session in a worktree

Pass --worktree (or -w) with a name:

claude --worktree feature-auth

By default the worktree is created under .claude/worktrees/feature-auth/ at your repository root, on a new branch named worktree-feature-auth. Run the command again with another name in a second terminal and you have a second isolated session. If you leave the name out, Claude makes one up.

Add .claude/worktrees/ to your .gitignore so the worktree contents do not show up as untracked files in your main checkout.
The first time in a directory, run claude once and accept the trust dialog, or an interactive --worktree exits with an error asking you to.
You can also ask in a session: "work in a worktree".

A worktree is a fresh checkout

Gitignored files such as .env are not there, and dependencies are not installed. Ask Claude to install them, or run your setup in the worktree folder. To copy gitignored files in automatically, put a .worktreeinclude file at the repository root, written like a .gitignore:

.env
.env.local

Only files that match a pattern and are gitignored get copied, so tracked files are never duplicated. It copies rather than links, so keep it to the few small files you need. The documentation's own example lists a secrets config, so think before you add anything sensitive. For big folders such as node_modules, the docs point to a worktree.symlinkDirectories setting, or you can keep the install command in your CLAUDE.md.

Which branch does it start from?

By default a new worktree branches from the repository's default branch on the remote, usually main, so it starts clean. If it should carry your unpushed commits instead, set worktree.baseRef to "head" in your settings. The setting takes those two values only. To start from a particular existing branch, create the worktree with git yourself.

What a worktree shares with your main checkout

The repository's .git directory, so git commit works from inside a worktree.
Plugins installed at project scope.
Permission approvals. Choosing "Yes, and don't ask again" for a command in a worktree session saves the rule to the main checkout's .claude/settings.local.json, so it applies in every worktree of the repository and outlives the worktree. On Windows, and in a few other setups, the rule stays with that worktree instead. See the permission modes guide for how permissions work.
Project skills, agents and commands, in some cases, when the worktree has none of its own.

It keeps the session inside its worktree

While a session is isolated, Claude Code blocks edits that target a path in the main checkout, commands whose working directory resolves to the main checkout, and git commands redirected into it. The documentation is clear about the limit of this: it reads paths and command text, and does not track which files a shell command writes. A plain cp or a shell redirect into the main checkout is not refused by these checks. Those commands fall under your normal permissions and sandbox settings.

Cleaning up

When you exit an interactive worktree session, Claude Code checks for work that removal would delete. If the worktree is clean and the session was unnamed, it removes the worktree and its branch. A named session asks you first. If there are changes or new commits, it asks whether to keep or remove it, and removing deletes the directory and its branch along with that work. To come back to a kept worktree, run the claude --worktree <name> --resume command it prints on exit.

One exception: a non-interactive run (claude -p --worktree, see running from a script) has no exit prompt, so you remove those yourself with git worktree remove <path>. If git says the worktree is locked, run git worktree unlock <path> first.

Subagents in their own worktrees

Ask Claude to "use worktrees for your agents", or make it permanent for a custom subagent by adding isolation: worktree to its frontmatter. Each subagent gets a temporary worktree that is removed automatically when it finishes without changes.

Good to know

Worktrees isolate file edits only. Subagents split work inside one session, and the documentation compares the approaches on its parallel agents page.
They need a git repository. Other version control systems need hooks to replace the git steps.
Some behavior changed between versions, so check the documentation for yours.

Try it on something harmless

In a small test repository, add .claude/worktrees/ to .gitignore.
Run claude -w try-one, ask for a tiny change, and exit. Choose to keep the worktree when asked.
Run git worktree list to see it, then claude -w try-one --resume to go back.

This follows Anthropic's worktrees documentation as we read it in October 2026. We are not affiliated with Anthropic. We wrote this from the documentation and have not tested every case. Where this page and the documentation disagree, the documentation wins.

The free loop-stop skill gives long tasks a limit and a stop rule. If you want a second pair of eyes on your CLAUDE.md and settings, the Tune-Up Kit is a checklist for exactly that.