Claude Code with Git Worktree: Parallel Development
Claude Code's built-in worktree support lets you run multiple AI coding sessions in parallel, each on its own branch with full isolation. This guide covers everything you need to know about using git worktree with Claude Code for faster, safer parallel development.
What Is Claude Code Worktree?
Claude Code includes a --worktree flag that automatically creates a new git worktree and starts a Claude session inside it. Instead of manually running git worktree add, Claude Code handles the entire workflow: creating the worktree, checking out a new branch, and launching a session scoped to that isolated directory.
This matters because Claude Code modifies files as it works. Without isolation, two Claude sessions editing the same repo would conflict with each other. Git worktrees give each session its own working directory with its own checked-out branch, while sharing the same git history and object store. The result: true parallel development with zero merge conflicts during work.
When you use claude --worktree, Claude Code creates a worktree in a sibling directory (typically named after the branch), starts a session there, and lets you work independently of your main checkout. You can run as many worktree sessions as you need, each tackling a different feature, bug fix, or refactor simultaneously.
How to Set Up Git Worktree for Claude Code
Step 1: Ensure You Have a Git Repository
Claude Code's worktree feature requires a git repository. If you haven't initialized one yet, do so first:
cd your-project
git init
git add -A
git commit -m "Initial commit"If you already have a repo, make sure your working tree is clean (all changes committed or stashed) before creating worktrees. This avoids unexpected state in the new checkout. For more on adding worktrees to an existing repo, see our git worktree add tutorial.
Step 2: Using the claude --worktree Flag
Launch Claude Code with the --worktree flag. You can optionally provide a branch name or let Claude create one for you:
# Create a worktree with an auto-generated branch name
claude --worktree
# Create a worktree on a specific new branch
claude --worktree feat/add-auth
# Create a worktree from an existing remote branch
claude --worktree origin/fix/login-bugClaude Code will create the worktree directory, check out the branch, and start an interactive session scoped to that directory. You will see output confirming the worktree path and branch name.
Step 3: Managing the Worktree
After your Claude session finishes, the worktree remains on disk. You can re-enter it manually, or clean it up:
# List all worktrees
git worktree list
# Remove a worktree when done
git worktree remove ../your-project-feat-add-auth
# Prune stale worktree references
git worktree pruneRunning Multiple Claude Sessions in Parallel
The real power of Claude Code worktrees is running several sessions at once. Combined with tmux (or any terminal multiplexer), you can have multiple Claude agents working on different tasks simultaneously. For a deeper look at this pattern, see our guide on parallel AI agents with git worktree.
tmux + Git Worktree Workflow
The recommended approach is to open a tmux session, split it into panes, and launch a separate Claude worktree in each pane. Each Claude instance works in its own isolated worktree, so there are no file conflicts:
# Start a new tmux session
tmux new-session -s claude-parallel
# Pane 1: Feature work
claude --worktree feat/user-dashboard
# Split horizontally (Ctrl-b %)
# Pane 2: Bug fix
claude --worktree fix/api-timeout
# Split again (Ctrl-b ")
# Pane 3: Refactor
claude --worktree refactor/db-queriesAutomated Multi-Session Script
You can script the entire setup to launch multiple Claude worktree sessions at once:
#!/bin/bash
# launch-parallel-claude.sh
# Starts 3 Claude worktree sessions in tmux panes
SESSION="claude-work"
tmux new-session -d -s $SESSION
# First pane: feature branch
tmux send-keys -t $SESSION "claude --worktree feat/new-api" Enter
# Second pane
tmux split-window -h -t $SESSION
tmux send-keys -t $SESSION "claude --worktree fix/validation" Enter
# Third pane
tmux split-window -v -t $SESSION
tmux send-keys -t $SESSION "claude --worktree chore/update-deps" Enter
# Attach to the session
tmux attach-session -t $SESSIONWith this setup, you can monitor all three sessions at a glance and switch between panes with Ctrl-b followed by an arrow key.
Claude Code Worktree Skills
Claude Code includes a built-in /worktree skill that you can invoke during an interactive session. This skill creates a new worktree and spawns a sub-agent inside it, without you needing to leave your current session.
# Inside an active Claude Code session, type:
/worktree feat/sidebar-redesign "Redesign the sidebar component with collapsible sections"
# Claude will:
# 1. Create a new worktree on branch feat/sidebar-redesign
# 2. Spawn a sub-agent in that worktree
# 3. The sub-agent works independently while you continue in your current sessionSkills and worktrees work together naturally. Any skill that reads or writes files operates within the context of its own worktree, so changes from one session never leak into another. The sub-agent spawned by the /worktree skill has the same capabilities as a top-level Claude session, including access to all other skills and tools.
When the sub-agent completes its task, the changes remain in the worktree branch. You can then review the diff, merge the branch, or continue iterating on it from a new session.
Best Practices for Claude Code with Worktrees
Give Each Session a Clear, Descriptive Branch Name
Use conventional branch prefixes like feat/, fix/, or refactor/. This makes it easy to identify which worktree is which when you run git worktree list.
When to Use Worktree vs. Regular Sessions
Use worktrees when you want to run multiple Claude sessions at the same time, or when you want to isolate experimental changes from your main working directory. For single-task work where you are only running one Claude session, a regular session in your main checkout is simpler and sufficient. See our git worktree best practices guide for more on when worktrees make sense.
Limit the Number of Concurrent Sessions
Each Claude session consumes API credits and system resources. For most workflows, two to four parallel sessions is the sweet spot. Running more than that can make it hard to review and integrate the results.
Clean Up Worktrees When Done
Worktrees consume disk space and can clutter your project directory. After merging a branch, remove its worktree with git worktree remove and delete the merged branch. Run git worktree prune periodically to clean up stale references.
Use a CLAUDE.md File for Consistency
Place a CLAUDE.md file in your repo root with project-specific instructions. Because worktrees share the same git history, every Claude session (regardless of which worktree it runs in) will pick up the same configuration, ensuring consistent behavior across all your parallel agents.
Common Issues and Solutions
node_modules in Worktrees
Each worktree gets its own working directory, but node_modules is not shared. You need to run npm install(or your package manager's equivalent) inside each new worktree. Claude Code usually handles this automatically when it detects a package.json, but if you see missing-module errors, install dependencies manually.
.env Files Not Present in Worktrees
Because .env files are typically in .gitignore, they will not appear in new worktrees. You need to copy them manually or create a script that symlinks your env files into each worktree:
# Copy .env to a new worktree
cp .env ../your-project-feat-branch/.env
# Or symlink it (changes apply to all worktrees)
ln -s $(pwd)/.env ../your-project-feat-branch/.envWorktree Lock Conflicts
If you try to check out a branch that is already checked out in another worktree, git will refuse. Each worktree must be on a unique branch. If you see a "fatal: branch is already checked out" error, either use a different branch name or remove the conflicting worktree first.
Large Repos and Disk Space
Worktrees share git objects (the .git directory), so they use less space than full clones. However, build artifacts, dependencies, and generated files are not shared. For large projects, clean up worktrees promptly and consider using git worktree prune to remove dangling references.
Summary
Claude Code's worktree integration turns git worktrees into a first-class workflow for parallel AI development. Whether you use the --worktree CLI flag or the /worktree skill from within a session, you get isolated branches that let multiple Claude agents work without stepping on each other. Pair it with tmux for visibility across sessions, follow the best practices above, and you will have a highly productive parallel development setup.