worktree-coordination

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Worktree Coordination Skill

工作树协调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).

Agent Teams (CC 2.1.33+): 当设置
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
时，原生Agent Teams提供内置的协作体生命周期管理、点对点消息传递和共享任务列表。本Skill的自定义文件锁定和协调注册表将被Teams的原生协调功能取代。仅在非Teams工作树场景（例如，无共享团队的多个独立Claude Code会话）中使用本Skill。

Commands

命令

/worktree-status

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

显示所有活跃Claude Code实例的状态。

用法：

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

操作：

运行
```
cc-worktree-status
```
查看所有活跃实例
检查过期实例（超过5分钟无心跳）
查看所有实例的文件锁定情况

输出包含：

实例ID和分支
当前任务（若已设置）
健康状态（ACTIVE/STALE）
每个实例锁定的文件

/worktree-claim <file-path>

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-claim src/auth/login.ts

操作：

检查文件是否已被锁定
若已被其他实例锁定，显示锁定持有者
若可用，获取锁定

/worktree-release <file-path>

Release lock on a file.

Usage:

/worktree-release src/auth/login.ts

释放文件的锁定。

用法：

/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-sync [--check-conflicts] [--pull-decisions]

操作：

```
--check-conflicts
```
: 对其他活跃分支运行merge-tree
```
--pull-decisions
```
: 显示其他实例的近期架构决策

/worktree-decision <decision>

Log an architectural decision visible to all instances.

Usage:

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

记录所有实例可见的架构决策。

用法：

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

Automatic Behaviors

自动行为

File Lock Check (PreToolUse Hook)

文件锁定检查（PreToolUse钩子）

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

每30秒：

更新本实例的心跳时间戳
清理过期实例（超过5分钟无心跳）
释放孤立锁定

Cleanup (Stop Hook)

清理（Stop钩子）

When Claude Code exits:

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

当Claude Code退出时：

释放本实例持有的所有文件锁定
从协调注册表注销

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     │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│  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

注册表 Schema

Located at

.claude/coordination/registry.json

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"
    }
  ]
}

位于

.claude/coordination/registry.json

：

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

CLI 命令

Available in

bin/

bash

undefined

在

bin/

目录下可用：

bash

undefined

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]

undefined

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

undefined

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)

每个工作树一个任务 - 每个Claude Code实例应专注于一个功能/任务
提前认领文件 - 在开始处理共享文件前使用
```
/worktree-claim
```
记录决策 - 使用
```
/worktree-decision
```
记录影响其他实例的决策
检查冲突 - 在提交前运行
```
cc-worktree-sync --check-conflicts
```
清理资源 - 正常退出Claude Code以释放锁定（Ctrl+C或/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

查看锁定持有者：
```
/worktree-status
```
若实例已过期：
```
cc-worktree-status --clean
```
若为合法持有：与其他实例协调或处理其他文件

"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

心跳钩子会在首次使用工具时自动注册。若问题持续：

检查
```
.claude-local/instance-id.txt
```
是否存在
验证
```
.claude/coordination/
```
是否已正确创建符号链接

Related Skills

Key Decisions

关键决策

Decision	Choice	Rationale
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

决策	选择	理由
锁定粒度	文件级	在冲突预防和并行工作灵活性之间取得平衡
过期检测	5分钟心跳超时	足够长以适应正常暂停，足够短以实现快速清理
注册表位置	.claude/coordination/	通过符号链接跨工作树共享，受版本控制
锁定获取	写入/编辑时自动获取	无需手动干预即可防止意外冲突
决策共享	集中式日志	所有实例可实时查看架构决策

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

关键词： worktree, status, instances, active, who 解决的问题：

如何查看所有活跃Claude Code实例
检查哪些文件被锁定
查找过期实例

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

关键词： lock, claim, release, conflict, blocked 解决的问题：

如何防止实例间的文件冲突
编辑前认领文件
完成后释放锁定

decision-sync

Keywords: decision, sync, share, coordinate Solves:

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

关键词： decision, sync, share, coordinate 解决的问题：

跨实例共享架构决策
查看其他实例的决策
协调工作树之间的方法

conflict-prevention

Keywords: conflict, merge, overlap, collision Solves:

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

关键词： conflict, merge, overlap, collision 解决的问题：

提交前检查合并冲突
避免工作重叠
协调并行开发

worktree-coordination

Original

Translation

Worktree Coordination Skill

工作树协调Skill

Commands

命令

/worktree-status

/worktree-status

/worktree-claim <file-path>

/worktree-claim <file-path>

/worktree-release <file-path>

/worktree-release <file-path>

/worktree-sync

/worktree-sync

/worktree-decision <decision>

/worktree-decision <decision>

Automatic Behaviors

自动行为

File Lock Check (PreToolUse Hook)

文件锁定检查（PreToolUse钩子）

Heartbeat (Lifecycle Hook)

心跳（生命周期钩子）

Cleanup (Stop Hook)

清理（Stop钩子）

File Lock States

文件锁定状态

Registry Schema

注册表 Schema

CLI Commands

CLI 命令

Create new coordinated worktree

创建新的协调工作树

Check status of all worktrees

检查所有工作树的状态

Sync context and check conflicts

同步上下文并检查冲突

Best Practices

最佳实践

Troubleshooting

故障排除

"File is locked by another instance"

"文件已被其他实例锁定"

"Instance not registered"

"实例未注册"

Related Skills

相关Skill

Key Decisions

关键决策

Capability Details

能力详情

status-check

status-check

file-locking

file-locking

decision-sync

decision-sync

conflict-prevention

conflict-prevention