Claude Code with Git Worktree: Parallel Development
Claude Code's built-in worktree workflow 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 new git worktree, starts a session inside it, 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 worktree name or let Claude generate one for you:
# Create a worktree with an auto-generated branch name
claude --worktree
# Create a named worktree session
claude --worktree feature-auth
# Start another named worktree session
claude --worktree bugfix-loginClaude Code will create the worktree directory, create the associated 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
When the session ends, Claude Code cleans up automatically if no changes were made. If the session produced changes or commits, Claude prompts you to keep or remove the worktree. You can also inspect or clean it up manually:
# 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.
Worktree-Isolated Subagents
Claude Code supports running subagents in isolated git worktrees via the isolation: "worktree" parameter on the Agent tool. When set, the subagent gets a temporary worktree so parallel agent work does not collide in the same checkout. The claude --worktree flag also lets you start a top-level session in a new worktree.
# Inside an active Claude Code session, ask:
use worktrees for your agents
# Claude will create isolated worktrees for subagents so they can
# work in parallel without editing the same checkout.Each worktree-isolated subagent gets its own working directory, so changes from one agent do not leak into another. If a subagent finishes without changes, Claude Code can clean up that temporary worktree automatically.
When a subagent completes its task with changes, you can 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 worktree-isolated subagents 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.