Parallel Development with 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

Quick Reference

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