worktree-coordination_skill

This skill coordinates multiple Claude Code worktrees, enabling synchronized status, file locking, and conflict checks across parallel sessions.

TypeScript

75

GitHub Stars

1

Bundled Files

2 months ago

Catalog Refreshed

4 months ago

First Indexed

Readme & install

Copy the install command, review bundled files from the catalogue, and read any extended description pulled from the listing source.

Installation

Preview and clipboard use veilstrat where the catalogue uses aiagentskills.

npx veilstrat add skill yonatangross/orchestkit --skill worktree-coordination

SKILL.md7.6 KB

Overview

This skill coordinates multiple Claude Code instances working across separate worktrees to avoid collisions and share context. It provides file-level locking, a lightweight registry, heartbeat lifecycle management, and decision logging so parallel sessions stay synchronized. Use it for independent Claude sessions that are not using native Agent Teams.

How this skill works

The skill maintains a registry in .claude/coordination/registry.json that records active instances, file locks, and a decisions log. A heartbeat updates each instance every 30 seconds, cleans stale entries (no heartbeat > 5 min), and releases orphaned locks. Hooks run before write/edit operations to block or acquire locks and on stop to release resources.

When to use it

Working in parallel Claude Code sessions across multiple worktrees without Agent Teams enabled
You need to prevent simultaneous edits to the same files
Sharing architectural decisions or task state across independent instances
Checking for merge/merge-tree conflicts before committing
Cleaning up stale sessions and orphaned locks

Best practices

Run one focused task per worktree to limit cross-instance interference
Claim shared files early with /worktree-claim before editing
Run cc-worktree-sync --check-conflicts prior to commits or merges
Log architectural decisions with /worktree-decision so others can see rationales
Exit Claude Code cleanly to trigger automatic lock release and unregister

Example use cases

Two developers run independent Claude Code instances on feature branches and avoid editing the same auth files
A single developer experiments in multiple worktrees and wants automatic lock cleanup for stale sessions
Teams share architecture choices: record a decision like using Passport.js and surface it across instances
CI or local scripts run cc-worktree-status --clean to remove stale locks before automated merges
Before a stacked PR, run cc-worktree-sync --check-conflicts to detect merge-tree conflicts across branches

FAQ

When CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, use native Agent Teams. This skill is intended only for non-Teams worktree coordination.

How are stale instances detected?

An instance with no heartbeat for more than five minutes is marked STALE and cleaned up by the heartbeat hook.

Where is the coordination data stored?

Registry and lock data live under .claude/coordination/registry.json and should be shared across worktrees via a symlink.