Git Worktree Workflow Skill

Version: 1.1.0 Created: 2025-12-30 Last Updated: 2026-01-02 Category: Development

Overview

Git worktrees allow you to have multiple working directories from a single repository, enabling parallel development workflows with Claude Code. This is essential for running multiple Claude instances on different tasks simultaneously.

Quick Start

# 1. Create worktree for new feature branch
git worktree add -b feature-api ../project-api main

# 2. Run Claude in worktree
cd ../project-api && claude "Implement the feature"

# 3. After completion, merge and cleanup
cd ../project
git merge feature-api
git worktree remove ../project-api
git branch -d feature-api

When to Use

• Running multiple Claude agents on different features
• Testing changes while continuing development
• Code review with live comparison
• Parallel bug fixes across branches
• Subagent verification workflows
• A/B implementation comparisons
• CI/CD parallel job execution

Concepts

What is a Worktree?

Main repo: /project (on main branch)
Worktree 1: /project-feature-a (on feature-a branch)
Worktree 2: /project-feature-b (on feature-b branch)
Worktree 3: /project-hotfix (on hotfix branch)

All share the same

.git

Basic Commands

Create a Worktree

# Create worktree for existing branch
git worktree add ../project-feature feature-branch

# Create worktree with new branch
git worktree add -b new-feature ../project-new-feature main

# Create worktree for detached HEAD (testing)
git worktree add --detach ../project-test HEAD

List Worktrees

git worktree list
# Output:
# /project           abc1234 [main]
# /project-feature   def5678 [feature-a]
# /project-hotfix    ghi9012 [hotfix-123]

Remove Worktree

# Remove after merging
git worktree remove ../project-feature

# Force remove (discards changes)
git worktree remove --force ../project-abandoned

# Prune stale worktrees
git worktree prune

Parallel Claude Workflows

Pattern 1: Feature + Review

Run development and review in parallel:

# Terminal 1: Development Claude
cd /project-feature
claude "Implement the new authentication module"

# Terminal 2: Review Claude
cd /project
claude "Review the authentication changes in feature-auth branch"

Pattern 2: Multi-Feature Development

Work on multiple features simultaneously:

# Setup worktrees
git worktree add -b feature-api ../project-api main
git worktree add -b feature-ui ../project-ui main
git worktree add -b feature-tests ../project-tests main

# Run Claude in each (separate terminals)
cd ../project-api && claude "Build REST API endpoints"
cd ../project-ui && claude "Create React components"
cd ../project-tests && claude "Write integration tests"

Pattern 3: Subagent Verification

Main Claude spawns verification in separate worktree:

# Main Claude working in /project
# Creates verification worktree:
git worktree add --detach ../project-verify HEAD

# Spawns subagent to verify:
cd ../project-verify && claude -p "Verify the implementation works correctly"

Pattern 4: A/B Implementation

Compare two approaches:

# Create two worktrees from same point
git worktree add -b approach-a ../project-a main
git worktree add -b approach-b ../project-b main

# Different Claude instances try different solutions
cd ../project-a && claude "Implement caching using Redis"
cd ../project-b && claude "Implement caching using Memcached"

# Compare results
diff -r ../project-a/src ../project-b/src

Best Practices

Do

1. Use descriptive naming convention:

   <project>-<purpose>

2. Create worktrees in sibling directories (not inside project)
3. Commit or stash changes before removing worktrees
4. Prune stale worktrees regularly
5. Document active worktrees in team communication
6. Clean up merged worktrees promptly

Don't

1. Create worktrees inside the main project directory
2. Leave uncommitted changes in worktrees before removal
3. Forget to merge/push changes from worktrees
4. Create excessive worktrees (manage actively)
5. Use worktrees for long-lived branches (use separate clones)
6. Skip the cleanup step after merging

Naming Convention

# Pattern: <project>-<purpose>
../project-feature-auth      # Feature work
../project-hotfix-123        # Bug fix
../project-review            # Code review
../project-test              # Testing
../project-experiment        # Experiments

Workspace Organization

/workspace/
├── project/                 # Main development
├── project-feature-a/       # Active features
├── project-feature-b/
├── project-review/          # Review worktree
└── project-archive/         # Completed features (before cleanup)

Cleanup Script

#!/bin/bash
# cleanup-worktrees.sh

# Remove merged branches
git branch --merged main | grep -v main | while read branch; do
    worktree=$(git worktree list | grep "$branch" | awk '{print $1}')
    if [ -n "$worktree" ]; then
        echo "Removing worktree: $worktree"
        git worktree remove "$worktree"
    fi
done

# Prune stale references
git worktree prune

Integration with Claude Code

CLAUDE.md Configuration

Add to project CLAUDE.md:

## Worktree Workflow

When running parallel tasks:
1. Create worktree: `git worktree add -b <branch> ../<project>-<purpose> main`
2. Work in isolated directory
3. Commit changes normally
4. Return to main and merge
5. Remove worktree: `git worktree remove ../<worktree>`

Headless Mode in Worktrees

# Automate worktree operations
WORKTREE="../project-auto-$(date +%s)"
git worktree add -b auto-task "$WORKTREE" main

cd "$WORKTREE"
claude -p "Complete the task in task.md" --output result.md

# Collect results
cp result.md ../results/
git worktree remove "$WORKTREE"

Error Handling

chmod -R u+w <worktree>

git worktree prune

.git/worktrees/<name>/locked

Advanced: CI/CD Integration

GitHub Actions Parallel Jobs

jobs:
  parallel-claude:
    strategy:
      matrix:
        task: [lint, test, security]
    steps:
      - uses: actions/checkout@v4

      - name: Create worktree
        run: |
          git worktree add -b ${{ matrix.task }} ../work-${{ matrix.task }}

      - name: Run Claude task
        run: |
          cd ../work-${{ matrix.task }}
          claude -p "Run ${{ matrix.task }} analysis"

Execution Checklist

git worktree add -b <branch> <path> main

git worktree list

cd <path>

pwd

claude "<task>"

git add . && git commit -m "message"

git log

cd <main-project>

pwd

git merge <branch>

git log

git worktree remove <path>

git worktree list

git branch -d <branch>

git branch

git worktree prune

Metrics

Related Skills

• repo-sync - Manage multiple repositories
• sparc-workflow - Systematic development process
• agent-orchestration - Multi-agent coordination

Version History

• 1.1.0 (2026-01-02): Added Quick Start, Error Handling table, Metrics, Execution Checklist, Best Practices Do/Don't, updated frontmatter with version/category/related_skills
• 1.0.0 (2025-12-30): Initial release based on Claude Code best practices