Worktree Coordination Skill

Agent Teams (CC 2.1.33+): When

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

is set, native Agent Teams provides built-in teammate lifecycle management, peer-to-peer messaging, and shared task lists. This skill's custom file locking and coordination registry are superseded by Teams' native coordination. Use this skill only for non-Teams worktree scenarios (e.g., multiple independent Claude Code sessions without a shared team).

Commands

/worktree-status

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

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

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

/worktree-claim <file-path>

/worktree-claim src/auth/login.ts

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

/worktree-release <file-path>

/worktree-release src/auth/login.ts

/worktree-sync

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

1. --check-conflicts

   : Run merge-tree against other active branches

2. --pull-decisions

   : Show recent architectural decisions from other instances

/worktree-decision <decision>

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

Automatic Behaviors

File Lock Check (PreToolUse Hook)

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)

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

Cleanup (Stop Hook)

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

.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": "-01-08T14:30:00Z",
      "last_heartbeat": "-01-08T14:45:32Z"
    }
  },
  "file_locks": {
    "src/auth/oauth.ts": {
      "instance_id": "cc-auth-a1b2c3",
      "acquired_at": "-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": "-01-08T14:40:00Z"
    }
  ]
}

CLI Commands

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"

1. Check

   .claude-local/instance-id.txt

   exists
2. 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

Capability Details

status-check

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

file-locking

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

decision-sync

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

conflict-prevention

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