How to Use Git Worktrees with Claude Code (Full Guide)

A git worktree lets you check out several branches of one repository into separate folders at the same time — so two Claude Code sessions can run in parallel without editing each other’s files. It’s a built-in git command (git worktree), so you don’t need any extra tools.

If you run more than one Claude Code session on the same repository, you’ve probably watched it happen: two agents edit the same file, overwrite each other’s work, and leave you with a diff that makes no sense. Worktrees are the fix.

This guide covers git worktrees end to end: what they are, the exact commands, the workflows that matter when you’re running agents in parallel, the gotchas that trip everyone up, and how to skip the manual plumbing if you do this often.

Last updated: June 19, 2026.

What a git worktree actually is

A git worktree is a second working copy of your repository that shares the same underlying .git history. Each worktree checks out its own branch, keeps its own files on disk, and operates completely independently, but it doesn’t duplicate the repo. All worktrees share the same objects, refs, and config with the original.

One repo, several desks. Each desk has its own papers spread out, but they all pull from the same filing cabinet. That shared history is what makes worktrees lighter than cloning the repo again, and it’s why a commit you make in one worktree is instantly available to all the others.

This matters for Claude Code specifically because agents work autonomously and fast. Give two agents the same working directory and they’ll race each other. Give each its own worktree and they can’t collide: different files on disk, different branch, zero overlap.

Here’s how a worktree compares to the two things people usually reach for instead:

	Working copy	Git history	Disk cost	Good for
Branch (`git checkout`)	One, shared	Shared	None	Switching context in a single session
Worktree (`git worktree add`)	Separate per worktree	Shared	Checked-out files only	Running parallel sessions/agents on one repo
Clone (`git clone`)	Separate	Separate copy	Full repo each time	A fully independent copy of the project

A worktree is the middle option: separate files on a separate branch, but one shared history, exactly what parallel agents need.

Quick start

If you just want the commands, here’s the whole loop:

# Create a worktree on a new branch
git worktree add ../myrepo-auth -b feature/auth

# Work in it (open a Claude Code session here)
cd ../myrepo-auth && claude

# When done, merge from your main repo
cd ../myrepo && git merge feature/auth

# Remove the worktree and prune the reference
git worktree remove ../myrepo-auth

Everything below explains the why, the variations, and what breaks.

Setting up worktrees for Claude Code, step by step

1. Create a worktree with a new branch

From your repo root:

git worktree add ../myrepo-auth -b feature/auth

This creates a new directory ../myrepo-auth containing a full working copy, checked out to a brand-new feature/auth branch. Keeping it outside your main repo folder (note the ../) is the convention; it stops your editor and tooling from treating the worktree as part of the main project.

To base the worktree on an existing branch instead of a new one, drop the -b:

git worktree add ../myrepo-hotfix main

2. Open a Claude Code session in the worktree

cd ../myrepo-auth
claude

That’s it. Claude now operates entirely inside this isolated copy. It can edit files, run commands, and commit, all on feature/auth, without touching your main working directory.

3. Repeat for each parallel task

git worktree add ../myrepo-login -b fix/login-bug
cd ../myrepo-login
claude

Now two agents run at the same time on separate branches, with no file conflicts between them.

4. Merge when the work is done

cd /path/to/myrepo
git merge feature/auth

5. Clean up

git worktree remove ../myrepo-auth

If you already deleted the directory by hand, clear the leftover reference with:

git worktree prune

To see every worktree currently attached to the repo:

git worktree list

Claude Code’s built-in worktree support

You don’t always have to run the git worktree commands yourself. Per the official Claude Code worktrees documentation, Claude Code has native worktree integration:

Start a session in a fresh worktree: claude --worktree <name> (or -w) creates the worktree and opens Claude inside it.
Switch mid-session: ask Claude to “work in a worktree” and it’ll create one and move into it.
The Claude desktop app creates a worktree for every new session automatically, so parallel sessions are isolated out of the box.

Do subagents (`/agents`) run in worktrees?

Not by default, and this trips people up. Per the Claude Code subagents documentation, subagents you spawn with /agents (the Task tool) are isolated at the context-window level, but they share the same working directory and files as the main session. Two subagents told to edit the same file can still overwrite each other.

You can opt into file isolation for agents:

Ask Claude to “use worktrees for your agents,” or
Add isolation: worktree to a custom subagent’s frontmatter to make it permanent.

Without that, parallel agents rely on coordination: the orchestrating agent has to give each one a non-overlapping set of files to own. So worktrees aren’t just a manual trick; they’re the mechanism Claude Code uses to keep parallel agents from clobbering each other once you turn isolation on.

Real worktree workflows for parallel agents

The mechanics are simple; the value is in when you reach for them. These are the patterns that come up constantly once you’re running agents in parallel.

Two features at once. Spin up a worktree per feature and point an agent at each. They build independently, you review and merge each branch on its own schedule. This is the bread-and-butter case.

Hotfix without losing your place. You’re mid-feature when a production bug lands. Instead of stashing and switching branches (and forcing your agent to lose context), create a worktree off main, fix the bug there, merge it, and your feature branch never moved.

Throwaway experiments. Want Claude to try a risky refactor or a new library without endangering your real branch? A worktree is a disposable sandbox; if it goes sideways, delete the directory and the branch, and nothing else is affected.

Reviewing a branch or PR. Check out someone else’s branch in a worktree to run it, test it, or have Claude review it, all without disrupting whatever you have open in your main copy.

Background agents. Worktrees let an agent grind on a long task (a big migration, a test-suite cleanup) in its own copy while you keep working in yours.

Running several Claude Code sessions at once

Worktrees solve the file conflict, but you still have to manage the sessions. Each worktree needs its own terminal running its own claude process. A few ways people handle this:

Terminal tabs or splits. The simplest approach: one tab per worktree. It works, but with two repos and a few worktrees each you’re quickly juggling six or eight tabs and trying to remember which is which.
tmux. A tmux window or pane per worktree keeps sessions alive even if you close the terminal, but you’re hand-rolling the layout and naming.
VS Code multi-root workspaces. Add each worktree as a folder and run Claude in an integrated terminal per folder.
A purpose-built tool. This is the gap crystl fills (more on that below).

The friction is real either way: the more worktrees you run, the more session bookkeeping you do.

The gotchas nobody warns you about

Untracked and ignored files don’t come along

This is the one that surprises everyone. A worktree only checks out tracked files. Anything git ignores (node_modules, .env, build output, .venv, caches) does not carry over. A fresh worktree often won’t run until you install dependencies and copy your environment files:

cd ../myrepo-auth
npm install            # or pnpm install, pip install, etc.
cp ../myrepo/.env .    # secrets are gitignored, so copy them manually

If your agent reports “module not found” or a missing key in a brand-new worktree, this is almost always why.

Branch-name collisions

Git won’t let the same branch be checked out in two worktrees at once. If you delete a worktree’s directory without removing it properly, git still thinks the branch is checked out somewhere:

fatal: 'feature/auth' is already checked out at '/path/that/no/longer/exists'

Fix it with git worktree prune, but you have to remember to run it.

Directory sprawl

Three or four worktrees and your filesystem fills with myrepo, myrepo-auth, myrepo-login, myrepo-refactor scattered around. There’s no single place to see what’s active without running git worktree list.

The merge-back dance

Finishing up means switching to the main repo, merging the branch, removing the worktree, and deleting the branch: four steps, easy to half-complete, tedious to repeat dozens of times a week.

Automating it: isolated sessions in crystl

If you’re doing this regularly with Claude Code, crystl, a macOS terminal built for running agents, turns the whole worktree workflow into one click. When you create an isolated shard, crystl handles the worktree, the branch, and the directory for you:

One click to create. crystl makes the worktree, checks out a new branch, and opens the session, no commands.
No sprawl. Worktrees live in a managed hidden directory; you never see them in Finder.
Visual separation. Each shard is color-coded by its parent gem (project), so you always know which session belongs to which repo.
One-click merge. The Isolation panel rebases onto main, fast-forwards, and cleans up. Or close the shard and crystl prompts you to merge, keep, or discard.
Resume orphaned branches. Stranded worktrees show up with commit and change counts so you can reattach and pick up where you left off.

The manual workflow is perfectly good and works anywhere git does. Automation just removes the bookkeeping once you’re past doing it occasionally.

When to use worktrees vs. a regular session

Not every task needs isolation. Quick questions, code reviews, and read-only exploration are fine in a normal session. Reach for a worktree (manual or automated) when:

Two or more agents need to edit the same repo at the same time
You want to prototype something risky without touching your working branch
You’re fixing a bug on main while a feature branch is in flight
You want an agent to run autonomously in the background

FAQ

Do git worktrees copy my node_modules or .env? No. Worktrees only include tracked files. You’ll need to install dependencies and copy ignored files (like .env) into each new worktree.

Can two Claude Code sessions edit the same repository safely? Only if each runs in its own worktree (or its own clone). In the same working directory, two agents will overwrite each other. Worktrees give each one isolated files on a separate branch.

Do Claude Code subagents (/agents) use git worktrees? Not automatically. Subagents are isolated at the context-window level but share the main session’s working directory. To give them isolated files, add isolation: worktree to a custom subagent’s frontmatter or ask Claude to “use worktrees for your agents.”

How many worktrees can I have? As many as you want; they’re cheap because they share git history. You’re limited by disk space for the checked-out files and by how many sessions you can actually keep track of.

Do worktrees use a lot of disk? Far less than re-cloning. They share the .git object store; only the checked-out working files take extra space.

How do I list or remove worktrees? git worktree list shows them all; git worktree remove <path> deletes one; git worktree prune clears stale references for directories that were deleted manually.

Worktrees vs. branches vs. cloning — what’s the difference? A branch is a pointer in one working copy. A clone is a full, separate repo with its own history. A worktree sits in between: a separate working copy on its own branch, but sharing one history, which is exactly what you want for parallel agents.

Getting started

The manual approach works anywhere git is installed, with no extra tools. If you’d rather skip the setup-and-cleanup loop, grab crystl for free and create an isolated shard on your next parallel task.