What are git worktrees and how do they work with Claude Code?

A git worktree is a separate working directory linked to the same git repository, each checked out to a different branch. With Claude Code, you can run a separate claude session in each worktree simultaneously. Each session has its own files, its own branch, its own context — but they share git history. This means you can run 3-4 parallel Claude Code agents without any file conflicts, context collisions, or branch interference.

How do I create a git worktree for a Claude Code session?

Run: git worktree add ../my-feature-branch -b feature/my-feature. This creates a new directory ../my-feature-branch checked out to a new branch. Then cd ../my-feature-branch && claude to start a Claude Code session in that isolated context. To list all worktrees: git worktree list. To remove one when done: git worktree remove ../my-feature-branch.

What is the /enter-worktree skill in Claude Code?

The /enter-worktree skill (also called EnterWorktree) is a built-in Claude Code capability that creates a temporary git worktree, runs an agent in it, and optionally cleans up afterward. It's used by harness agents to isolate their work from the main working tree. The skill creates the worktree, executes work in it, and returns the branch name so you can merge or discard the changes.

Can I run multiple Claude Code instances at the same time?

Yes — and git worktrees are the recommended way to do it. Without worktrees, two Claude Code instances in the same directory would conflict: both could try to edit the same files, causing merge conflicts or overwritten work. With worktrees, each instance works in its own directory on its own branch. They're fully isolated until you choose to merge. You can run as many parallel instances as your machine has RAM/CPU for.

What are good use cases for running parallel Claude Code agents?

Best use cases: (1) A/B implementation — ask two agents to solve the same problem differently, then compare and pick the better solution. (2) Independent features — front-end work in one worktree, back-end in another, with no conflicts. (3) Research + implementation — one agent researches an approach while another implements a known solution. (4) Test writing — one agent writes tests while another fixes the bugs those tests reveal. (5) Refactoring passes — agent 1 cleans module A while agent 2 cleans module B.

How do I merge worktree changes back to main?

The worktree is just a regular git branch. Merge as normal: cd to your main repo directory, then git merge feature/my-feature (or git rebase). The worktree's branch appears in git branch -a just like any other branch. Once merged, remove the worktree: git worktree remove ../my-feature-branch, then delete the branch: git branch -d feature/my-feature.

Claude Code Worktrees

Run multiple Claude Code agents simultaneously on isolated git branches — no conflicts, full parallelism.

Why Worktrees?

By default, a single Claude Code session works in your repo's main working directory. If you open a second session in the same directory while the first is running, both agents edit the same files — leading to conflicts and overwritten work.

Git worktrees solve this: each worktree is a separate directory checked out to its own branch. Each Claude Code session gets full isolation. You can run 3, 4, or more parallel agents without any interference.

Quick Setup

Create a worktree for each parallel task

# Create worktree + new branch in one command
git worktree add ../feature-auth -b feature/auth
git worktree add ../feature-ui -b feature/ui

This creates two sibling directories: ../feature-auth/ and ../feature-ui/, each on their own branch.

Open a separate terminal for each worktree

# Terminal 1
cd ../feature-auth && claude

# Terminal 2
cd ../feature-ui && claude

Each session starts with a fresh context. They share git history but have fully separate working files.

Work in parallel — no conflicts

Both agents can read and write freely. Changes in feature-auth never appear in feature-ui until you merge.

Merge and clean up

# In your main repo directory:
git merge feature/auth
git merge feature/ui

# Remove the worktrees when done
git worktree remove ../feature-auth
git worktree remove ../feature-ui

# Delete the branches
git branch -d feature/auth feature/ui

The /enter-worktree Skill

Claude Code has a built-in /enter-worktree skill that automates worktree lifecycle management for agent tasks. When you ask Claude to use it:

Creates a temporary worktree from your current branch
Runs the specified work inside it (isolated from your main tree)
Returns the branch name with all changes — you choose whether to merge or discard
Auto-cleans the worktree directory if no changes were made

How the harness uses it: The Claude Code agent harness uses EnterWorktree internally when spawning subagents with isolation: "worktree". This is how the system runs experiments and moonshot tasks without risking the main working tree. You can invoke the same mechanism with /enter-worktree in your session.

Best Use Cases for Parallel Agents

Pattern	Setup	Benefit
A/B implementation	Two worktrees, same prompt to both agents	Compare two solutions; pick the better one
Independent features	One worktree per feature	No coordination needed; merge at end of day
Test + fix	Agent 1: write tests. Agent 2: fix code	Tests and fixes land on separate branches; merge both
Refactoring passes	Agent 1: clean module A. Agent 2: clean module B	Large refactors complete in half the wall-clock time
Research + implement	Agent 1 explores approach. Agent 2 implements known solution	Parallel discovery without blocking shipping

Worktree Commands Reference

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

# Create worktree from existing branch
git worktree add <path> <existing-branch>

# List all worktrees
git worktree list

# Remove a worktree (directory must be clean)
git worktree remove <path>

# Force-remove (discards uncommitted changes)
git worktree remove --force <path>

# Prune stale worktree refs
git worktree prune

Limitations

You can't check out the same branch in two worktrees. Each worktree must be on a unique branch.
The .git directory is shared — git operations that modify global state (e.g. config changes) affect all worktrees.
CLAUDE.md is shared — if both agents read the same CLAUDE.md, their instructions are identical. Use worktree-specific prompts in your session start message.
Auto-memory is per-project-path — agents in /main/ and ../feature-auth/ have different memory paths. Memories written in a worktree won't appear in the main tree's sessions.

Related Guides

Automation & /loop — schedule recurring agents and background tasks
Claude Code Hooks — run shell commands on tool events
Permissions Guide — configure allow lists and permission modes
Memory & CLAUDE.md — persistent context across sessions
All Claude Code Skills — back to the full directory

Claude Code Worktrees

Why Worktrees?

Quick Setup

The /enter-worktree Skill

Best Use Cases for Parallel Agents

Worktree Commands Reference

Limitations

Related Guides

More Claude Code Tools