git-worktrees

What this skill does

# Git Worktrees for Claude Code

## Overview

Run multiple Claude Code sessions in parallel on different branches using Git worktrees. This skill provides simple scripts and workflows to set up, manage, and clean up worktrees, enabling true parallel development without conflicts.

**Why Worktrees?**
- **Parallel Development**: Run multiple Claude Code instances simultaneously
- **Zero Conflicts**: Each worktree has independent file state
- **Fast Context Switching**: No need to stash/commit when switching tasks
- **Isolated Experiments**: Try different approaches without affecting main work
- **Long-Running Tasks**: Let Claude work in background while you continue in main

---

## Quick Start

### 1. Create a New Worktree (Super Easy!)

Just run the interactive script:

```bash
scripts/create_worktree.sh
```

This will:
- ✅ Prompt for feature name
- ✅ Create a new branch
- ✅ Set up the worktree
- ✅ Open in VS Code / editor
- ✅ Give you the Claude Code setup command

**That's it!** The script handles all complexity.

---

### 2. View All Worktrees

```bash
scripts/list_worktrees.sh
```

Shows a clean, formatted list of all your worktrees with their branches and status.

---

### 3. Clean Up Old Worktrees

```bash
scripts/cleanup_worktrees.sh
```

Interactive removal of merged or abandoned worktrees.

---

## Core Workflow

### Pattern 1: Parallel Feature Development

**Scenario:** You want Claude to build feature A while you work on feature B.

**Steps:**

1. **Create worktree for feature A:**
   ```bash
   scripts/create_worktree.sh
   # Enter: feature-a
   # Script creates: ../repo-feature-a/
   ```

2. **Open Claude Code in the new worktree:**
   - The script outputs the path
   - Open Claude Code and navigate to that directory
   - Run `/init` to orient Claude

3. **Give Claude the task:**
   ```
   "Build the user authentication feature with OAuth support"
   ```

4. **Continue your work in main:**
   - Your original directory is unchanged
   - No conflicts, no waiting
   - Claude works in parallel

5. **When both are done, merge:**
   ```bash
   # Review Claude's work
   cd ../repo-feature-a
   git log

   # If good, merge back
   git checkout main
   git merge feature-a

   # Clean up
   scripts/cleanup_worktrees.sh
   ```

---

### Pattern 2: Long-Running Refactor

**Scenario:** You want Claude to refactor a large module while you continue development.

**Steps:**

1. **Create refactor worktree:**
   ```bash
   scripts/create_worktree.sh
   # Enter: refactor-auth-module
   ```

2. **Start Claude in refactor worktree:**
   ```
   "Refactor the authentication module to use dependency injection"
   ```

3. **Continue your daily work in main:**
   - No interruption
   - No merge conflicts
   - Check progress periodically

4. **Review and integrate when ready:**
   ```bash
   cd ../repo-refactor-auth-module
   git log --oneline
   # Review changes

   # Merge when satisfied
   git checkout main
   git merge refactor-auth-module
   ```

---

### Pattern 3: Multiple AI Agents (Advanced)

**Scenario:** You want 3 Claude instances working on different features simultaneously.

**Steps:**

1. **Create 3 worktrees:**
   ```bash
   scripts/create_worktree.sh  # feature-api-endpoints
   scripts/create_worktree.sh  # feature-ui-dashboard
   scripts/create_worktree.sh  # feature-email-notifications
   ```

2. **Open 3 Claude Code sessions:**
   - Session 1: `../repo-feature-api-endpoints/`
   - Session 2: `../repo-feature-ui-dashboard/`
   - Session 3: `../repo-feature-email-notifications/`

3. **Assign tasks to each Claude:**
   - Claude 1: "Build REST API endpoints for user management"
   - Claude 2: "Create admin dashboard UI"
   - Claude 3: "Implement email notification system"

4. **Monitor progress:**
   ```bash
   scripts/list_worktrees.sh
   ```

5. **Merge features as they complete:**
   ```bash
   # Feature by feature
   git checkout main
   git merge feature-api-endpoints
   git merge feature-ui-dashboard
   git merge feature-email-notifications

   # Clean up
   scripts/cleanup_worktrees.sh
   ```

---

### Pattern 4: Hotfix While Development Continues

**Scenario:** Production bug needs immediate fix while Claude is working on a feature.

**Steps:**

1. **Claude is already working in a feature worktree**
   - Let it continue, don't interrupt

2. **Create hotfix worktree from main:**
   ```bash
   scripts/create_worktree.sh
   # Enter: hotfix-login-bug
   # Choose base branch: main
   ```

3. **Fix the bug yourself or with another Claude session:**
   ```bash
   cd ../repo-hotfix-login-bug
   # Make fixes
   git add .
   git commit -m "Fix login redirect bug"
   ```

4. **Merge hotfix to main:**
   ```bash
   git checkout main
   git merge hotfix-login-bug
   git push origin main
   ```

5. **Sync feature worktree with latest main:**
   ```bash
   cd ../repo-feature-xyz
   scripts/sync_worktree.sh
   # Merges latest main into feature branch
   ```

---

## Essential Scripts

### scripts/create_worktree.sh

**Interactive worktree creation with all the right defaults.**

**What it does:**
1. Prompts for feature name
2. Validates git repo
3. Creates branch from main (or specified base)
4. Sets up worktree in parallel directory
5. Outputs setup instructions

**Usage:**
```bash
scripts/create_worktree.sh

# Prompts:
# Feature name: my-feature
# Base branch (default: main):
#
# Creates: ../repo-my-feature/
# Branch: my-feature
```

**Advanced usage:**
```bash
# Create from specific branch
scripts/create_worktree.sh --base develop

# Specify location
scripts/create_worktree.sh --dir ~/worktrees/my-feature
```

---

### scripts/list_worktrees.sh

**Shows all active worktrees with status.**

**Output:**
```
╔════════════════════════════════════════════════╗
║            Active Git Worktrees                ║
╚════════════════════════════════════════════════╝

📁 Main Worktree
   Path: /home/user/project
   Branch: main
   Status: clean

📁 Feature Worktrees
   Path: /home/user/project-feature-api
   Branch: feature-api
   Status: 2 uncommitted changes

   Path: /home/user/project-refactor
   Branch: refactor-auth
   Status: clean
```

---

### scripts/cleanup_worktrees.sh

**Interactive cleanup of old worktrees.**

**Features:**
- Lists all worktrees with merge status
- Identifies merged branches (safe to remove)
- Prompts for confirmation
- Safely removes worktree and branch

**Usage:**
```bash
scripts/cleanup_worktrees.sh

# Output:
# Found 3 worktrees
#
# 1. feature-api (merged to main) - Safe to remove
# 2. feature-dashboard (not merged) - Keep
# 3. old-experiment (not merged, 30 days old) - Consider removing
#
# Which worktrees to remove? (1,3): 1
```

---

### scripts/sync_worktree.sh

**Keep worktree up-to-date with main branch.**

**What it does:**
1. Fetches latest from remote
2. Merges main into current worktree branch
3. Handles conflicts with guidance

**Usage:**
```bash
# From within a worktree
cd ../repo-feature-api
scripts/sync_worktree.sh

# Or specify worktree
scripts/sync_worktree.sh ../repo-feature-api
```

---

## Claude Code Integration

### Important: Run /init in Each Worktree

When you open a new Claude Code session in a worktree, **always run `/init` first**:

```
/init
```

This ensures Claude:
- Understands the codebase structure
- Has proper context
- Can navigate files correctly

### Recommended Claude Code Workflow

1. **Create worktree** (using script)
2. **Open Claude Code** in worktree directory
3. **Run `/init`** to orient Claude
4. **Give task** to Claude
5. **Monitor** via `git log` or file watching
6. **Review** when complete
7. **Merge** if satisfied
8. **Cleanup** worktree

---

## Best Practices

### Naming Conventions

**Good names:**
- `feature-user-auth` ✅
- `refactor-api-layer` ✅
- `hotfix-login-bug` ✅
- `experiment-new-db` ✅

**Bad names:**
- `test` ❌ (too vague)
- `wt1` ❌ (meaningless)
- `fixes` ❌ (unclear)

**Recommended format:**
```
<type>-<short-description>

Types:
- feature-*
- refactor-*
- hotfix-*
-