Agent skill
worktree
Manage git worktrees for parallel development. Use to work on multiple branches simultaneously without stashing or switching contexts.
Install this agent skill to your Project
npx add-skill https://github.com/johnlindquist/claude/tree/main/skills/worktree
SKILL.md
Git Worktree Manager
Work on multiple branches simultaneously using git worktrees.
Prerequisites
# Git 2.5+ (worktrees built-in)
git --version
CLI Reference
List Worktrees
# List all worktrees
git worktree list
# Porcelain format (machine-readable)
git worktree list --porcelain
Create Worktree
# Create from existing branch
git worktree add ../feature-branch feature-branch
# Create new branch
git worktree add -b new-feature ../new-feature main
# Specific path
git worktree add /path/to/worktree branch-name
# Detached HEAD at commit
git worktree add --detach ../temp abc123
Remove Worktree
# Remove worktree
git worktree remove ../feature-branch
# Force remove (uncommitted changes)
git worktree remove --force ../feature-branch
# Prune stale worktrees
git worktree prune
Worktree Operations
# Move worktree
git worktree move ../old-path ../new-path
# Lock worktree (prevent pruning)
git worktree lock ../feature-branch
git worktree lock --reason "long-running task" ../feature-branch
# Unlock
git worktree unlock ../feature-branch
Workflow Patterns
Parallel Feature Development
# Main repo working on feature-a
cd ~/repos/myproject
git checkout feature-a
# Create worktree for feature-b
git worktree add ../myproject-feature-b feature-b
# Now you have two checkouts:
# ~/repos/myproject (feature-a)
# ~/repos/myproject-feature-b (feature-b)
Quick Bug Fix
# Currently working on feature
cd ~/repos/myproject
# Create worktree for hotfix
git worktree add ../myproject-hotfix -b hotfix/urgent main
# Fix bug in worktree
cd ../myproject-hotfix
# make changes
git commit -am "fix: urgent bug"
git push origin hotfix/urgent
# Create PR
gh pr create --base main --title "Hotfix: urgent bug"
# Clean up
cd ../myproject
git worktree remove ../myproject-hotfix
Review PR
# Create worktree for PR branch
git fetch origin pull/123/head:pr-123
git worktree add ../myproject-pr-123 pr-123
# Review and test
cd ../myproject-pr-123
npm install
npm test
# Clean up after review
cd ../myproject
git worktree remove ../myproject-pr-123
git branch -D pr-123
Long-Running Comparison
# Worktree for baseline
git worktree add ../myproject-baseline main
# Run tests on both
cd ~/repos/myproject
npm test > /tmp/feature-tests.log
cd ../myproject-baseline
npm test > /tmp/baseline-tests.log
diff /tmp/baseline-tests.log /tmp/feature-tests.log
Directory Structure
Recommended layout:
~/repos/
├── myproject/ # Main worktree (main branch)
├── myproject-feature-a/ # Feature worktree
├── myproject-feature-b/ # Another feature
└── myproject-hotfix/ # Hotfix worktree
Or nested:
~/repos/myproject/
├── main/ # Main worktree
├── features/
│ ├── auth/ # Feature worktree
│ └── ui/ # Feature worktree
└── hotfix/ # Hotfix worktree
Beads with Worktrees
When using beads (task tracker) with worktrees, disable the daemon:
# In shell config
export BEADS_NO_DAEMON=1
# Or per-command
bd --no-daemon ready
bd --no-daemon create "task"
Common Issues
Branch Already Checked Out
# Error: 'branch' is already checked out at '/path'
# Solution: Use different branch or remove other worktree
git worktree remove /path/to/other
Stale Worktree References
# Clean up deleted worktrees
git worktree prune
# Verbose output
git worktree prune --verbose
Shared Resources
Each worktree shares:
.gitdirectory (refs, objects)- Remote configurations
- Hooks
Each worktree has separate:
- Working directory
- Index (staging area)
- HEAD
Scripts
Create Feature Worktree
#!/bin/bash
FEATURE=$1
BASE=${2:-main}
git worktree add -b feature/$FEATURE ../${PWD##*/}-$FEATURE $BASE
cd ../${PWD##*/}-$FEATURE
npm install
echo "Worktree created at $(pwd)"
Cleanup Old Worktrees
#!/bin/bash
# Remove worktrees for merged branches
for wt in $(git worktree list --porcelain | grep "^worktree" | cut -d' ' -f2); do
branch=$(git -C "$wt" branch --show-current)
if git branch --merged main | grep -q "$branch"; then
echo "Removing merged worktree: $wt ($branch)"
git worktree remove "$wt"
fi
done
git worktree prune
Best Practices
- Use descriptive paths - Include branch name in directory
- Install dependencies - Run npm/yarn install in each worktree
- Prune regularly - Clean up stale references
- Don't nest worktrees - Keep them sibling directories
- Lock long-running - Prevent accidental pruning
- Separate IDE workspace - Each worktree gets own IDE window
- Disable beads daemon - Prevent database conflicts
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
johnlindquist/claude
testgen
Generate tests using AI and run test suites. Use for generating unit tests, running coverage reports, and mutation testing.
johnlindquist/claude
article
Generate technical articles and documentation using AI. Use for writing blog posts, documentation, and technical content.
johnlindquist/claude
packx
Bundle code context for AI. ALWAYS use --limit 49k unless user explicitly requests otherwise. Use for creating shareable code bundles and preparing context for LLMs.
johnlindquist/claude
long-agent
Manage long-running agent sessions. Use for tracking progress in extended tasks, maintaining context across long sessions, and managing multi-step workflows.
johnlindquist/claude
db
Database operations for SQLite, PostgreSQL, and MySQL. Use for queries, schema inspection, migrations, and AI-assisted query generation.
johnlindquist/claude
investigate
Debug and investigate code issues using search and AI analysis. Use when stuck on bugs, tracing execution flow, or understanding complex code.
Didn't find tool you were looking for?