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 directory but have independent working directories.

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

Use descriptive naming convention: <project>-<purpose>
Create worktrees in sibling directories (not inside project)
Commit or stash changes before removing worktrees
Prune stale worktrees regularly
Document active worktrees in team communication
Clean up merged worktrees promptly

Don't

Create worktrees inside the main project directory
Leave uncommitted changes in worktrees before removal
Forget to merge/push changes from worktrees
Create excessive worktrees (manage actively)
Use worktrees for long-lived branches (use separate clones)
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:

Create worktree: git worktree add -b <branch> ../<project>-<purpose> main
Work in isolated directory
Commit changes normally
Return to main and merge
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

Error Cause Solution

Branch already checked out Branch exists in another worktree Remove existing worktree or use different branch

Cannot remove worktree Uncommitted changes present Commit, stash, or force remove

Permission errors Directory not writable chmod -R u+w <worktree> then remove

Stale worktree references Worktree directory deleted manually Run git worktree prune

Lock file exists Previous operation interrupted Remove .git/worktrees/<name>/locked file

Path already exists Directory exists at target path Choose different path or remove existing directory

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

Step Command Verification

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

git worktree list shows new entry

Navigate to worktree cd <path>

pwd shows worktree path

Run Claude task claude "<task>"

Task completes successfully

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

git log shows commit

Return to main cd <main-project>

pwd shows main path

Merge changes git merge <branch>

git log shows merge

Remove worktree git worktree remove <path>

git worktree list excludes entry

Delete branch git branch -d <branch>

git branch excludes branch

Prune stale git worktree prune

No stale references remain

Metrics

Metric Target Description

Worktree Creation Time <5s Time to create new worktree

Parallel Efficiency

80% CPU utilization across worktrees

Cleanup Rate 100% Worktrees removed after merge

Branch Isolation 100% No cross-worktree conflicts

Merge Success Rate

95% Clean merges without conflicts

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

git-worktree-workflow

Safety Notice

Copy this and send it to your AI assistant to learn