Worktree Coordination Skill

Overview

Manage multiple Claude Code instances working in parallel across git worktrees with automatic file locking, conflict detection, and decision synchronization.

When to Use

• Running multiple Claude Code instances simultaneously
• Working on related features in parallel
• Coordinating changes across git worktrees
• Preventing merge conflicts from parallel work

Commands

/worktree-status

Show status of all active Claude Code instances.

Usage: /worktree-status [--json] [--clean]

Actions:

1. Run cc-worktree-status to see all active instances
2. Check for stale instances (no heartbeat > 5 min)
3. View file locks across all instances

Output includes:

• Instance ID and branch
• Current task (if set)
• Health status (ACTIVE/STALE)
• Files locked by each instance

/worktree-claim

Explicitly lock a file for this instance.

Usage: /worktree-claim src/auth/login.ts

Actions:

1. Check if file is already locked
2. If locked by another instance, show who holds it
3. If available, acquire lock

/worktree-release

Release lock on a file.

Usage: /worktree-release src/auth/login.ts

/worktree-sync

Sync shared context and check for conflicts.

Usage: /worktree-sync [--check-conflicts] [--pull-decisions]

Actions:

1. --check-conflicts: Run merge-tree against other active branches
2. --pull-decisions: Show recent architectural decisions from other instances

/worktree-decision

Log an architectural decision visible to all instances.

Usage: /worktree-decision "Using Passport.js for OAuth" --rationale "Better middleware support"

Automatic Behaviors

File Lock Check (PreToolUse Hook)

Before any Write or Edit operation:

1. Check if file is locked by another instance
2. If locked → BLOCK with details about lock holder
3. If unlocked → Acquire lock and proceed

Heartbeat (Lifecycle Hook)

Every 30 seconds:

1. Update this instance's heartbeat timestamp
2. Clean up stale instances (no heartbeat > 5 min)
3. Release orphaned locks

Cleanup (Stop Hook)

When Claude Code exits:

1. Release all file locks held by this instance
2. Unregister from coordination registry

File Lock States

┌─────────────────────────────────────────────────────────┐
│  FILE: src/auth/oauth.ts                                │
├─────────────────────────────────────────────────────────┤
│  Status: LOCKED                                         │
│  Holder: cc-auth-a1b2c3                                 │
│  Branch: feature/user-authentication                    │
│  Task:   Implementing OAuth2 login flow                 │
│  Since:  2 minutes ago                                  │
├─────────────────────────────────────────────────────────┤
│  Action: Wait for release or use /worktree-release     │
└─────────────────────────────────────────────────────────┘

Registry Schema

Located at .claude/coordination/registry.json:

{
  "instances": {
    "cc-auth-a1b2c3": {
      "worktree": "/Users/dev/worktrees/feature-auth",
      "branch": "feature/user-authentication",
      "task": "Implementing OAuth2",
      "files_locked": ["src/auth/oauth.ts"],
      "started": "2026-01-08T14:30:00Z",
      "last_heartbeat": "2026-01-08T14:45:32Z"
    }
  },
  "file_locks": {
    "src/auth/oauth.ts": {
      "instance_id": "cc-auth-a1b2c3",
      "acquired_at": "2026-01-08T14:35:00Z",
      "reason": "edit"
    }
  },
  "decisions_log": [
    {
      "id": "dec-001",
      "instance_id": "cc-auth-a1b2c3",
      "decision": "Use Passport.js for OAuth",
      "rationale": "Better middleware support",
      "timestamp": "2026-01-08T14:40:00Z"
    }
  ]
}

CLI Commands

Available in bin/:

# Create new coordinated worktree
cc-worktree-new <feature-name> [--base <branch>]

# Check status of all worktrees
cc-worktree-status [--json] [--clean]

# Sync context and check conflicts
cc-worktree-sync [--check-conflicts] [--pull-decisions]

Best Practices

1. One task per worktree - Each Claude Code instance should focus on one feature/task
2. Claim files early - Use /worktree-claim before starting work on shared files
3. Log decisions - Use /worktree-decision for choices that affect other instances
4. Check conflicts - Run cc-worktree-sync --check-conflicts before committing
5. Clean up - Exit Claude Code properly to release locks (Ctrl+C or /exit)

Troubleshooting

"File is locked by another instance"

1. Check who holds it: /worktree-status
2. If instance is STALE: cc-worktree-status --clean
3. If legitimately held: Coordinate with other instance or work on different files

"Instance not registered"

The heartbeat hook will auto-register on first tool use. If issues persist:

1. Check .claude-local/instance-id.txt exists
2. Verify .claude/coordination/ is symlinked correctly

Capability Details

status-check

Keywords: worktree, status, instances, active, who Solves:

• How to see all active Claude Code instances
• Check which files are locked
• Find stale instances

file-locking

Keywords: lock, claim, release, conflict, blocked Solves:

• How to prevent file conflicts between instances
• Claim a file before editing
• Release a lock when done

decision-sync

Keywords: decision, sync, share, coordinate Solves:

• Share architectural decisions across instances
• See what other instances decided
• Coordinate approach between worktrees

conflict-prevention

Keywords: conflict, merge, overlap, collision Solves:

• Check for merge conflicts before committing
• Avoid overlapping work
• Coordinate parallel development