git-worktrees

Overview

Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching. This is essential when running multiple Claude Code instances in parallel.

Core principle: One worktree per Claude Code instance ensures isolation and prevents conflicts.

Announce at start: "I'm using the git-worktrees skill to set up an isolated workspace."

When to Use

• Running multiple Claude Code instances for different features
• Need to work on a feature branch while keeping main branch accessible
• Parallel development on separate tasks

Setup

# Create worktrees for parallel development
git worktree add ../dropkit-feature-a feature-a
git worktree add ../dropkit-feature-b feature-b

# Each worktree gets its own directory with full codebase
# Run Claude Code in each directory independently

Guidelines for Parallel Instances

1. One worktree per Claude Code instance - Never run multiple instances in the same directory
2. Separate branches - Each worktree should be on its own feature branch
3. Independent uv sync - Run uv sync in each worktree (creates separate .venv)
4. Tests run independently - Each worktree can run its own test suite without conflicts
5. Merge via main branch - When features are complete, merge branches to main

Managing Worktrees

# List all worktrees
git worktree list

# Remove a worktree when done
git worktree remove ../dropkit-feature-a

# Prune stale worktree entries
git worktree prune

Potential Conflicts to Avoid

| Resource | Risk | Mitigation | |----------|------|------------| | ~/.config/dropkit/ | User config is shared | Don't modify during parallel dev | | ~/.ssh/config | SSH config is shared | Coordinate droplet names | | DigitalOcean API | Creating droplets with same name | Use unique droplet names per worktree |

Quick Reference

| Situation | Action | |-----------|--------| | Starting parallel work | Create new worktree with feature branch | | New worktree created | Run uv sync to create isolated venv | | Feature complete | Merge to main, remove worktree | | Stale worktrees | Run git worktree prune |

Example Workflow

You: I'm using the git-worktrees skill to set up an isolated workspace.

[Create worktree: git worktree add ../dropkit-auth feature/auth]
[Run uv sync]
[Run uv run pytest - all passing]

Worktree ready at ../dropkit-auth
Tests passing
Ready to implement auth feature