Lesson 15: Git Worktree with Claude Code
Learning Objectives
After completing this lesson, you will be able to:
- Understand what git worktrees are and why they're useful
- Create and manage worktrees with Claude Code
- Use worktrees for parallel development
- Apply worktrees to common Claude Code workflows
- Clean up worktrees efficiently
Prerequisites
- Completed Lesson 9 - Git integration basics
- Git 2.7+ - Worktree support required
- Active development - Working on a project with multiple branches
Estimated Time: 20 minutes
What are Git Worktrees?
The Problem
Traditionally, to work on multiple branches simultaneously:
# ❌ Traditional approach - slow and error-prone
cd /project
git checkout feature-A
# make changes...
git commit -m "Work on feature A"
git checkout feature-B # Switches entire workspace
# Stash or commit feature-A changes
# make changes on feature-B...
Issues:
- Must commit or stash before switching
- Can't work on features in parallel
- Slow context switching
- Risk of accidentally mixing changes
The Solution: Git Worktrees
Git worktrees let you have multiple working directories for the same repository, all linked to the same git repository.
# ✅ Worktree approach - fast and safe
project/ # Main branch (main)
├── .git/ # Single git repository
project-feature-a/ # Worktree for feature-a
project-feature-b/ # Worktree for feature-b
project-hotfix/ # Worktree for hotfix
Benefits:
- Work on multiple branches simultaneously
- No need to stash or commit prematurely
- Faster context switching
- Isolated development environments
- Perfect for Claude Code multi-agent workflows!
Creating Worktrees with Claude Code
Basic Worktree Creation
Method 1: Using git directly
git worktree add ../project-feature-a feature-a
Method 2: With Claude Code
You> Create a worktree for the feature-a branch
Claude: [Uses Bash tool]
[Executes] git worktree add ../project-feature-a feature-a
✓ Worktree created at ../project-feature-a
You> Now open that worktree and show me the structure
Claude: [Reads the directory]
The worktree is ready with:
- Current branch: feature-a
- Files: [same as main]
- Unchanged: All files match main branch
Creating Worktrees from Commits
You> Create a worktree from commit abc1234 to investigate a bug
Claude: [Creates worktree]
git worktree add ../bug-investigation abc1234
✓ Worktree created at ../bug-investigation
Checked out commit: abc1234
Detached HEAD state
Listing Worktrees
You> Show me all worktrees for this project
Claude: [Uses Bash tool]
git worktree list
Output:
/home/user/project abc1234 [main]
/home/user/project-feature-a def5678 [feature-a]
/home/user/project-hotfix ghi9012 [hotfix-123]
Claude Code + Worktrees: Perfect Pair
Workflow 1: Parallel Feature Development
Scenario: You need to work on feature A while reviewing feature B.
Setup:
# Terminal 1: Feature A development
cd ~/project-feature-a
claude
You> Implement the user authentication feature
# Terminal 2: Feature B review
cd ~/project-feature-b
claude
You> Review the payment integration changes
Both Claude Code instances work independently in their own worktrees!
Workflow 2: Hotfix While Developing
Scenario: Critical bug found while working on a feature.
# Main development
~/project/ (working on feature-x)
# Create hotfix worktree
You> Create a worktree for hotfix branch from main
Claude: [Creates worktree]
cd ../project-hotfix
git checkout -b hotfix-critical-bug origin/main
# Switch to hotfix
You> Switch to the hotfix worktree and fix the bug
Claude: [Investigates and fixes bug]
Fixed! The issue was in auth.py line 45.
Committed fix to hotfix branch.
# Back to feature work
[Continue working on feature-x in main worktree]
No context switching required!
Workflow 3: Multi-Agent Worktrees
Combine worktrees with multi-agent automation:
project/
├── .agents/
├── worktrees/
│ ├── backend-api/ # Claude Code: Backend agent
│ ├── frontend-ui/ # Claude Code: Frontend agent
│ └── integration-tests/ # Claude Code: Test agent
└── scripts/
Orchestration script:
# Setup worktrees for agents
git worktree add ../backend-api feature/backend
git worktree add ../frontend-ui feature/frontend
git worktree add ../integration-tests feature/tests
# Start agents in their worktrees
./scripts/start-multi-agent-worktrees.sh
Each agent works in isolation!
Common Worktree Patterns
Pattern 1: Feature Branch Worktrees
# Before starting a new feature
You> Create a worktree for the new shopping-cart feature
Claude: [Executes]
git worktree add ../project-shopping-cart origin/main
cd ../project-shopping-cart
git checkout -b feature/shopping-cart
✓ Ready to develop shopping cart feature
When done:
# After merging and cleanup
You> Remove the shopping-cart worktree after merge
Claude: [Removes worktree]
git worktree remove ../project-shopping-cart
✓ Worktree removed
Pattern 2: PR Review Worktrees
# Create worktree to review PR
You> Create a worktree for PR #123
Claude: [Creates worktree from PR]
git worktree add ../pr-123-review origin/pr/123
cd ../pr-123-review
# Claude Code reviews the PR in isolation
You> Review this PR and suggest improvements
Pattern 3: Experiment Worktrees
# Try experimental changes safely
You> Create an experimental worktree for testing a refactor
Claude: [Creates worktree]
git worktree add ../experiment-refactor HEAD
# Make risky changes without affecting main worktree
Managing Worktrees
Listing Worktrees
You> Show all worktrees with their status
Claude: [Lists worktrees]
git worktree list --porcelain
worktree /home/user/project
HEAD abc1234
branch refs/heads/main
detached
worktree /home/user/project-feature-a
HEAD def5678
branch refs/heads/feature-a
worktree /home/user/project-bug-fix
HEAD ghi9012
branch refs/heads/bug-fix
Pruning Worktrees
Remove worktrees that have been deleted:
You> Clean up worktrees whose directories are gone
Claude: [Prunes worktrees]
git worktree prune
✓ Removed 3 stale worktree references
Moving Worktrees
Relocate a worktree:
You> Move the hotfix worktree to ~/projects/hotfix
Claude: [Moves worktree]
git worktree move ../project-hotfix ~/projects/hotfix
✓ Worktree moved
Worktree Best Practices
1. Organize Worktrees
Good:
~/projects/
├── main-project/ # Main development
├── project-feature-a/ # Feature A
├── project-hotfix-123/ # Hotfix #123
└── project-experiment/ # Experiments
Avoid:
~/random-locations/scattered-around/
2. Name Worktrees Clearly
Good:
project-feature-shopping-cartproject-hotfix-auth-bugproject-refactor-database
Bad:
project-1temptest
3. Clean Up Regularly
You> Check which worktrees can be removed
Claude: [Analyzes worktrees]
These worktrees have merged branches:
- project-feature-completed (branch merged to main)
- project-hotfix-deployed (branch deleted)
Safe to remove.
4. Use with Claude Code Sessions
Best practice: One Claude Code session per worktree
# Terminal 1
cd ~/project-feature-a
claude
# Work on feature A
# Terminal 2
cd ~/project-feature-b
claude
# Work on feature B
Each Claude instance has context for its worktree only!
Practical Examples
Example 1: Hotfix During Feature Development
# Working on feature in main worktree
~/project/ (on feature/new-ui)
# Critical bug report comes in
You> Create a worktree for urgent bug fix
Claude: [Creates worktree]
git worktree add ../project-hotfix-urgent origin/main
cd ../project-hotfix-urgent
git checkout -b hotfix/crash-bug
# Fix the bug
You> Investigate the crash bug and fix it
Claude: [Analyzes and fixes]
Found the issue! Null pointer in auth.py:67.
Fixed and committed.
# Deploy hotfix
[Create PR, merge, deploy]
# Return to feature work
cd ~/project
# Feature work untouched, ready to continue
Example 2: Parallel Feature Development with Claude Code
# Setup two features
git worktree add ../project-user-auth feature/user-auth
git worktree add ../project-payments feature/payments
# Terminal 1: User authentication
cd ~/project-user-auth
claude
You> Implement OAuth2 authentication
[Develops auth feature]
# Terminal 2: Payments (in parallel!)
cd ~/project-payments
claude
You> Implement Stripe integration
[Develops payment feature]
# Both features developed simultaneously!
# No branch switching, no stashing!
Example 3: Code Review in Worktree
# Review PR without cluttering main workspace
You> Create a worktree to review PR #456
Claude: [Creates worktree]
git worktree add ../pr-review-456 origin/pr/456
cd ../pr-review-456
# Review with Claude Code
You> Thoroughly review this PR and suggest improvements
Claude: [Reviews code]
Found 3 issues:
1. SQL injection vulnerability
2. Missing error handling
3. Inconsistent naming
[Claude creates PR comments or fixes directly]
# Cleanup after review
git worktree remove ../pr-review-456
Worktrees with Multi-Agent Claude Code
Ultimate Workflow: Worktrees + Multi-Agent
project/
├── .agents/
├── worktrees/
│ ├── backend/ # Backend agent workspace
│ ├── frontend/ # Frontend agent workspace
│ ├── tests/ # Test agent workspace
│ └── docs/ # Documentation agent workspace
└── scripts/
└── multi-agent-worktree.sh
Orchestration script:
#!/bin/bash
# multi-agent-worktree.sh
PROJECT_ROOT=$(pwd)
WORKTREES="$PROJECT_ROOT/worktrees"
# Create worktrees
git worktree add $WORKTREES/backend origin/main
git worktree add $WORKTREES/frontend origin/main
git worktree add $WORKTREES/tests origin/main
git worktree add $WORKTREES/docs origin/main
# Create branches
cd $WORKTREES/backend && git checkout -b feature/api-endpoints
cd $WORKTREES/frontend && git checkout -b feature-ui-components
cd $WORKTREES/tests && git checkout -b feature-test-coverage
cd $WORKTREES/docs && git checkout -b feature/api-documentation
# Start agents in their worktrees
gnome-terminal --working-directory=$WORKTREES/backend -- claude &
gnome-terminal --working-directory=$WORKTREES/frontend -- claude &
gnome-terminal --working-directory=$WORKTREES/tests -- claude &
gnome-terminal --working-directory=$WORKTREES/docs -- claude &
echo "✓ 4 agents started in isolated worktrees!"
Benefits:
- Complete isolation
- No file conflicts
- Independent git histories
- Parallel development
- Claude Code context per worktree
Troubleshooting
Issue: Worktree not found
You> Open the feature-a worktree
Claude: [Directory not found]
Error: ../project-feature-a doesn't exist
Solution: The worktree was removed or moved.
Check: git worktree list
Recreate if needed.
Issue: Branch already checked out
Error: feature-xyz is already checked out at ../project-feature-xyz
Solution: Either:
1. Use the existing worktree
2. Remove the existing worktree first
git worktree remove ../project-feature-xyz
Issue: Detached HEAD
You> Show the current branch in this worktree
Claude: [Shows detached HEAD]
Warning: HEAD is detached at abc1234
Solution: This is normal for worktrees from commits.
Create a branch if needed:
git checkout -b new-branch
✅ Check Your Understanding
-
What is a git worktree?
- A separate git repository
- A linked working directory for the same repo
- A git branch
- A stash
-
When should you use worktrees?
- Only for hotfixes
- When working on multiple branches simultaneously
- Never, just use branches
- Only with Claude Code
-
How do you remove a worktree?
- Just delete the directory
- git worktree remove
<path> - git branch -d
<branch> - git clean -fd
-
True or False: Worktrees share the same .git repository.
- True
- False
-
Why are worktrees good for Claude Code?
- They're not
- Each Claude Code session can have its own worktree
- Only for git operations
- They reduce memory usage
Answers: 1-b, 2-b, 3-b, 4-True, 5-b
Summary
In this lesson, you learned:
- What worktrees are - Multiple working directories for one repo
- Creating worktrees - Using git or Claude Code
- Claude Code integration - One session per worktree
- Common patterns - Feature development, hotfixes, reviews
- Multi-agent workflows - Combining worktrees with Lesson 14
- Cleanup - Removing and pruning worktrees
Next Steps
Combine worktrees with:
- Lesson 9: Git integration
- Lesson 14: Multi-agent automation
- Practice: Create worktrees for your current project
Further Reading
Master worktrees, master parallel development! 🚀