worktree-coordination

Show status of all active Claude Code instances.

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

Actions:

• Run cc-worktree-status to see all active instances

• Check for stale instances (no heartbeat > 5 min)

• 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:

• Check if file is already locked

• If locked by another instance, show who holds it

• 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:

• --check-conflicts: Run merge-tree against other active branches

• --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:

• Check if file is locked by another instance

• If locked → BLOCK with details about lock holder

• If unlocked → Acquire lock and proceed

Heartbeat (Lifecycle Hook)

Every 30 seconds:

• Update this instance's heartbeat timestamp

• Clean up stale instances (no heartbeat > 5 min)

• Release orphaned locks

Cleanup (Stop Hook)

When Claude Code exits:

• Release all file locks held by this instance

• 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

• One task per worktree - Each Claude Code instance should focus on one feature/task

• Claim files early - Use /worktree-claim before starting work on shared files

• Log decisions - Use /worktree-decision for choices that affect other instances

• Check conflicts - Run cc-worktree-sync --check-conflicts before committing

• Clean up - Exit Claude Code properly to release locks (Ctrl+C or /exit)

Troubleshooting

"File is locked by another instance"

• Check who holds it: /worktree-status

• If instance is STALE: cc-worktree-status --clean

• 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:

• Check .claude-local/instance-id.txt exists

• Verify .claude/coordination/ is symlinked correctly

Related Skills

• git-workflow - Git workflow patterns used within each coordinated worktree

• commit - Create commits with proper conventional format in each worktree

• stacked-prs - Manage dependent PRs that may span multiple worktrees

• architecture-decision-record - Document decisions shared via /worktree-decision

Key Decisions

| Lock granularity | File-level | Balances conflict prevention with parallel work flexibility

| Stale detection | 5 min heartbeat timeout | Long enough for normal pauses, short enough for quick cleanup

| Registry location | .claude/coordination/ | Shared across worktrees via symlink, version-controlled

| Lock acquisition | Automatic on Write/Edit | Prevents accidental conflicts without manual intervention

| Decision sharing | Centralized log | All instances see architectural decisions in real-time

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