Git Worktrees for Claude Code: The Missing Tutorial

If you’re running multiple Claude Code sessions on the same repo, you’ve likely run into this: two agents editing the same file, stomping on each other’s changes, producing garbage diffs. The fix is git worktrees — a built-in git feature that doesn’t get much attention.

This guide walks you through setting up worktrees manually for Claude Code, explains the gotchas, and shows you the fast path if you’d rather skip the plumbing.

What git worktrees actually are

A git worktree is a second (or third, or fourth) working copy of your repo that shares the same .git history. Each worktree checks out its own branch, has its own file state, and operates independently. Unlike cloning the repo again, worktrees are lightweight — they share objects, refs, and config with the original.

Think of it this way: one repo, multiple desks. Each desk has its own set of papers spread out, but they’re all working from the same filing cabinet.

Setting up worktrees manually for Claude Code

The step-by-step:

1. Create a worktree with a new branch

From your repo root:

git worktree add ../my-repo-feature-auth -b feature/auth

This creates a new directory ../my-repo-feature-auth with a full working copy checked out to a new feature/auth branch. The directory lives outside your main repo folder, which keeps things clean.

2. Open a Claude Code session in the worktree

cd ../my-repo-feature-auth
claude

That’s it. Claude now operates in this isolated copy. It can edit files, run commands, and make commits — all on the feature/auth branch without touching your main working directory.

3. Repeat for each parallel task

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

Now you have two Claude agents running simultaneously on separate branches, with zero file conflicts.

4. Merge when done

cd /path/to/original/repo
git merge feature/auth

5. Clean up the worktree

git worktree remove ../my-repo-feature-auth

Or if the directory was already deleted:

git worktree prune

The gotchas you’ll hit

Manual worktrees work, but there are rough edges when you’re doing this regularly.

Branch name collisions

If you forget to clean up a worktree but delete its directory, git remembers the branch is “checked out” in a worktree that no longer exists. You’ll get errors like:

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

Fix: git worktree prune clears stale references. But you have to remember to run it.

Directory sprawl

With three or four worktrees, you end up with my-repo, my-repo-feature-auth, my-repo-fix-login, my-repo-refactor-api scattered across your filesystem. There’s no single place to see what’s active.

Terminal tab chaos

Each worktree needs its own terminal session. With two repos and three worktrees each, you’re managing six terminal tabs and trying to remember which is which.

No easy merge-back flow

When you’re done, you need to switch to the main repo, merge the branch, delete the worktree, and delete the branch. Four commands, easy to forget a step, annoying to repeat.

How Crystl handles all of this automatically

If you’re using worktrees regularly with Claude Code, Crystl removes the manual setup entirely. When you create an isolated shard, Crystl handles the worktree creation, branch naming, and directory management behind the scenes.

What changes:

  • One click to create — Create an isolated shard from the Crystal Rail or shard menu. Crystl creates the worktree, checks out a new branch, and opens the session. No terminal commands needed.
  • No directory sprawl — Worktrees are managed in a hidden directory. You never see them in Finder or your editor’s sidebar.
  • 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 — Open the Isolation panel in the shard bar and choose Merge to main. Crystl rebases onto main, fast-forward merges, and cleans up automatically. Or close the shard — Crystl prompts you to merge, keep, or discard the branch.
  • Reopen worktrees — Orphaned branches appear in the Isolation panel with commit and change counts. Click to reattach and resume where you left off.

The manual worktree workflow is solid. It works. But if you’re doing it more than once a week, the automation pays for itself immediately.

When to use worktrees vs. regular sessions

Not every task needs isolation. Quick questions, code reviews, and read-only exploration are fine in a regular session. Use worktrees (manual or via isolated shards) when:

  • Two agents need to edit files in the same repo simultaneously
  • You want to prototype something without risking your working directory
  • You’re fixing a bug on main while a feature branch is in progress
  • You want Claude to work autonomously in the background without affecting your current state

Getting started

The manual approach works anywhere git does — no extra tools needed. If you want the automated version, grab Crystl for free and try creating an isolated shard on your next parallel task.