Git Worktrees for Parallel AI Development

Git worktrees are one of git’s most underused features. They let you check out multiple branches of the same repository simultaneously, each in its own directory. For AI-assisted development, they’re essential — they’re how you run two Claude Code agents on the same project without conflicts.

What is a git worktree?

Normally, a git repo has one working directory. You can only have one branch checked out at a time. To work on a different branch, you stash or commit your changes, switch branches, and switch back when you’re done.

A worktree creates a second (or third, or fourth) working directory linked to the same repo. Each worktree has its own branch checked out. Changes in one worktree don’t affect the others.

# You're on main in your project
cd ~/projects/my-app

# Create a worktree on a new branch
git worktree add ~/projects/my-app-feature feature/new-api

# Now you have:
# ~/projects/my-app/          → main branch
# ~/projects/my-app-feature/  → feature/new-api branch

Both directories share the same git history, but each has its own files and branch. Editing a file in one directory doesn’t change it in the other.

Why worktrees matter for AI coding

When you run Claude Code, it reads and edits files in your working directory. If two Claude Code sessions are working in the same directory, they’ll overwrite each other’s changes. This is the fundamental conflict problem with parallel AI development.

Worktrees solve this completely. Each Claude Code session gets its own worktree with its own branch:

# Session 1: Add authentication
git worktree add ../my-app-auth feature/auth
cd ../my-app-auth
claude "add JWT authentication to the API"

# Session 2: Write tests (in original directory)
cd ~/projects/my-app
claude "write integration tests for the payment flow"

Both agents work at full speed without blocking each other.

Common worktree commands

# Create a worktree with a new branch
git worktree add <path> -b <new-branch-name>

# Create a worktree with an existing branch
git worktree add <path> <existing-branch>

# List all worktrees
git worktree list

# Remove a worktree (after merging)
git worktree remove <path>

# Prune stale worktree references
git worktree prune

Practical workflow

Step 1: Create worktrees for each task

git worktree add ../my-app-auth -b feature/auth
git worktree add ../my-app-tests -b feature/tests

Step 2: Run Claude Code in each

Open separate terminal windows (or tabs) for each worktree and start Claude Code:

# Terminal 1
cd ../my-app-auth && claude "add user authentication"

# Terminal 2
cd ../my-app-tests && claude "write test suite for payments"

Step 3: Merge results

When each agent finishes, merge the branches back:

cd ~/projects/my-app
git merge feature/auth
git merge feature/tests

Or, if you’re using a tool like Crystl, you can merge directly from the UI — open the Isolation panel in the shard bar and choose Merge to main. It rebases, merges, and cleans up in one step.

Step 4: Clean up

git worktree remove ../my-app-auth
git worktree remove ../my-app-tests

Limitations

• You can’t check out the same branch in two worktrees. Each worktree needs its own branch.
• Large repos take more disk space. Each worktree is a full copy of the working directory (though they share git objects, so it’s less than a full clone).
• You need to manage the worktree lifecycle. Creating, merging, and removing worktrees adds overhead to your workflow.

Automating worktrees

The create-merge-cleanup cycle gets repetitive when you’re doing this multiple times a day. Crystl automates the entire process with isolated shards:

1. Create: Click Isolation ▾ in the shard bar and choose New Isolated Shard to create a worktree-backed session
2. Work: Each shard has its own working copy — agents can’t conflict
3. Merge: Open the Isolation panel and choose Merge to main — Crystl rebases, fast-forward merges, and cleans up in one step. Or close the shard and choose Merge to Main from the prompt.
4. Reopen: Orphaned branches appear in the Isolation panel for one-click reattachment
5. Warnings: If multiple shards are editing database schemas or migrations, Crystl warns you before merging so you avoid migration conflicts

You get the benefits of worktree-based isolation without managing the git commands. Each isolated shard is visually distinct in Crystl’s interface, so you can see at a glance which sessions are isolated and which branch they’re on.

When to use worktrees vs. branches

Use regular branches when you’re working on one thing at a time and switching between tasks sequentially.

Use worktrees when you need multiple tasks running simultaneously — especially when AI agents are involved. The moment you want two Claude Code sessions on the same repo, worktrees are the answer.