worktree-manager

使用 git worktree 和 Claude Code Agent 管理所有项目的并行开发。每个工作树都是仓库的隔离副本，位于不同分支，并集中存储在 `~/tmp/worktrees/`。这样，多个 Agent 就能同时工作而不会发生冲突。

<quick_start> 创建一个工作树并启动 Agent：

/worktree create feature/auth

Claude 将：

1. 分配端口（8100-8101）
2. 在 ~/tmp/worktrees/[project]/feature-auth 创建工作树
3. 安装依赖项
4. 为 Agent 创建 WORKTREE_TASK.md
5. 启动终端并运行 Claude Opus 4.6 Agent </quick_start>

原生 --worktree 标志（Claude Code v2.1.49+）

Claude Code 现在内置了工作树支持：

# Named worktree
claude --worktree feature-auth   # or: claude -w feature-auth

# Auto-generated name
claude -w

功能说明

• 在 <repo>/.claude/worktrees/<name>/ 创建工作树
• 分支：worktree-<name>（根据默认远程分支自动创建）
• 退出时：如果没有更改，则自动清理；如果存在更改，则提示保留或删除

提示： 将 .claude/worktrees/ 添加到 .gitignore

何时使用原生功能，何时使用此技能

场景	使用
快速隔离工作，单个 Agent	claude -w feature-name
多 Agent 团队、端口分配、注册表	此技能（worktree-manager）
子 Agent 隔离	Task 工具参数中的 isolation: "worktree"
非 git 版本控制系统（Perforce、SVN）	WorktreeCreate/WorktreeRemove 钩子

WorktreeCreate / WorktreeRemove 钩子

新增的钩子事件，用于与版本控制系统无关的工作树生命周期管理。配置后，这些钩子将替代默认的 git worktree 行为：

{
  "hooks": {
    "WorktreeCreate": [{
      "hooks": [{
        "type": "command",
        "command": "bash -c 'INPUT=$(cat); NAME=$(echo \"$INPUT\" | jq -r .name); mkdir -p /tmp/worktrees/$NAME && echo $NAME'"
      }]
    }],
    "WorktreeRemove": [{
      "hooks": [{
        "type": "command",
        "command": "bash -c 'INPUT=$(cat); PATH=$(echo \"$INPUT\" | jq -r .path); rm -rf $PATH'"
      }]
    }]
  }
}

何时使用钩子而非原生功能： 使用钩子的情况包括使用非 git 版本控制系统，或需要自定义隔离逻辑（例如 Docker 容器、远程开发服务器）。对于标准 git 仓库，建议使用原生 claude -w 标志或此技能的工作流。

注意： 这些钩子不支持匹配器。每个工作树生命周期事件触发一次。钩子通过 stdin JSON 接收 {name, path}。

<success_criteria> 满足以下条件时，工作树设置成功：

• 工作树已创建在 ~/tmp/worktrees/[project]/[branch-slug]
• 端口已分配并在全局注册
• 依赖项已安装
• Agent 已在终端中启动（Ghostty/iTerm2/tmux）
• 条目已添加到 ~/.claude/worktree-registry.json </success_criteria>

<current_state> Git 仓库： !git status --short --branch 2>/dev/null

现有工作树： !git worktree list 2>/dev/null

工作树注册表： !cat ~/.claude/worktree-registry.json 2>/dev/null | jq -r '.worktrees[] | "\(.project)/\(.branch) → \(.status)"' | head -10

可用端口： !cat ~/.claude/worktree-registry.json 2>/dev/null | jq '.portPool.allocated | length' || echo "0" 个已分配 </current_state>

<activation_triggers>

此技能的激活条件

触发短语：

• “为 X、Y、Z 创建工作树”
• “为功能 A、B、C 创建 3 个工作树”
• “为 feature/auth 创建新工作树”
• “我的工作树状态如何？”
• “显示所有工作树” / “显示此项目的工作树”
• “清理已合并的工作树”
• “在工作树 X 中启动 Agent”

调用方式

命令语法：

• /worktree create feature/auth - 创建单个工作树
• /worktree create feat1 feat2 feat3 - 创建多个工作树
• /worktree status - 检查所有工作树
• /worktree status --project myapp - 按项目筛选
• /worktree cleanup feature/auth - 删除工作树
• /worktree launch feature/auth - 在工作树中启动 Agent

</activation_triggers>

<file_locations>

</file_locations>

关键文件

文件	用途
~/.claude/worktree-registry.json	全局注册表 - 跟踪所有项目中的所有工作树
~/.claude/skills/worktree-manager/config.json	技能配置 - 终端、Shell、端口范围设置
~/.claude/skills/worktree-manager/scripts/	辅助脚本 - 可选，也可以手动完成所有操作
~/tmp/worktrees/	工作树存储位置 - 所有工作树都存放在此处
.claude/（每个项目中）	项目配置 - CLAUDE.md、钩子、权限、自定义 Agent
.claude/worktree.json（每个项目中）	项目配置 - 可选的自定义设置
WORKTREE_TASK.md（每个工作树中）	自动加载的任务提示词 - Agent 在启动时读取

</file_locations>

<core_concepts>

核心概念

集中式工作树存储

所有工作树都存放在 ~/tmp/worktrees/<project-name>/<branch-slug>/

~/tmp/worktrees/
├── obsidian-ai-agent/
│   ├── feature-auth/           # branch: feature/auth
│   ├── feature-payments/       # branch: feature/payments
│   └── fix-login-bug/          # branch: fix/login-bug
└── another-project/
    └── feature-dark-mode/

分支 Slug 约定

为确保文件系统安全，会将分支名称转换为 slug：

• feature/auth → feature-auth
• fix/login-bug → fix-login-bug

手动转换为 Slug： echo "feature/auth" | tr '/' '-'

端口分配

• 全局端口池：8100-8199（共 100 个端口）
• 每个工作树：分配 2 个端口（用于 API + 前端模式）
• 全局唯一：跟踪端口，避免不同项目间发生冲突

参见： reference/port-allocation.md，了解详细操作。

必需的默认设置

重要： 启动 Agent 时必须使用以下设置：

设置	值	原因
终端	Ghostty 或 iTerm2	自动检测，可在 config.json 中配置
模型	--model opus	Opus 4.6 别名（能力最强）
标志	--dangerously-skip-permissions	执行自主文件操作所必需

启动命令模式：

# Recommended: agent inherits .claude/ config (CLAUDE.md, hooks, permissions)
claude --model opus --dangerously-skip-permissions

# Or with explicit permission allowlist (safer, from .claude/settings.json):
claude --model opus --allowedTools "Bash(npm test),Bash(npm run build),Edit,Write,Read,Glob,Grep"

子 Agent 工作树隔离

可以将子 Agent 配置为在隔离的工作树中运行：

# In subagent frontmatter:
---
name: my-subagent
isolation: worktree
---

子 Agent 会在临时工作树中运行。完成后：

• 如果没有更改：自动清理
• 如果存在更改：保留更改以供审查

</core_concepts>

技能配置

位置：~/.claude/skills/worktree-manager/config.json

{
  "terminal": "ghostty",
  "terminalPreference": "auto",
  "enableNumberedTabs": true,
  "shell": "zsh",
  "defaultModel": "opus",
  "claudeCommand": "claude --model opus --dangerously-skip-permissions",
  "portPool": { "start": 8100, "end": 8199 },
  "portsPerWorktree": 2,
  "worktreeBase": "~/tmp/worktrees",
  "defaultCopyDirs": [".claude"],
  "envFilePriority": [".env.local", ".env", ".env.example"],
  "autoCleanupOnMerge": true
}

.claude/ 目录传播

创建工作树时，会复制整个 .claude/ 目录，使 Agent 继承项目级配置：

.claude/
├── CLAUDE.md              # Project instructions (auto-loaded by Claude Code)
├── settings.json          # Hooks and permissions
│   ├── hooks.PostToolUse  # Auto-format on Write|Edit (e.g., "bun run format || true")
│   └── permissions.allow  # Whitelisted bash commands for agents
├── agents/                # Custom subagent definitions
│   ├── build-validator.md # Validates builds pass
│   ├── code-architect.md  # Plans implementation
│   ├── code-simplifier.md # Refactors for clarity
│   └── verify-app.md      # End-to-end verification
└── PROJECT_CONTEXT.md     # Session continuity (project-context-skill)

这很重要，原因如下：

• CLAUDE.md：Agent 会读取项目约定、开发命令和技术栈
• 钩子：每次 Write/Edit 后都会自动格式化，确保不同 Agent 的代码风格一致
• 权限：Agent 无需提示即可运行预先批准的命令（例如 npm test、bun run build）
• 自定义 Agent：Agent 可以调度子 Agent（例如，用于端到端检查的 verify-app.md）

钩子示例（settings.json）：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "bun run format || true" }]
      }
    ]
  }
}

工作流

创建多个工作树

用户说：“为 feature/auth、feature/payments 和 fix/login-bug 创建 3 个工作树”

你执行（可以通过子 Agent 并行处理）：

For EACH branch (can run in parallel):

1. SETUP
   PROJECT=$(basename $(git remote get-url origin 2>/dev/null | sed 's/\.git$//') || basename $(pwd))
   REPO_ROOT=$(git rev-parse --show-toplevel)
   BRANCH_SLUG=$(echo "feature/auth" | tr '/' '-')
   WORKTREE_PATH=~/tmp/worktrees/$PROJECT/$BRANCH_SLUG

2. ALLOCATE PORTS
   Find 2 unused ports from 8100-8199, add to registry

3. CREATE WORKTREE
   mkdir -p ~/tmp/worktrees/$PROJECT
   git worktree add $WORKTREE_PATH -b $BRANCH

4. COPY PROJECT CONFIG (.claude/ directory)
   cp -r .claude $WORKTREE_PATH/ 2>/dev/null || true
   Copy .env.local or .env as appropriate

5. CREATE WORKTREE_TASK.md
   Create detailed task file for agent

6. INSTALL DEPENDENCIES
   Detect package manager, run install command

7. VALIDATE (optional)
   Start server, health check, stop

8. REGISTER IN GLOBAL REGISTRY
   Update ~/.claude/worktree-registry.json with entry

9. LAUNCH AGENT
   ghostty -e "cd $WORKTREE_PATH && claude --model opus --dangerously-skip-permissions"

AFTER ALL COMPLETE:
- Report summary table to user

查看状态

使用脚本：

~/.claude/skills/worktree-manager/scripts/status.sh
~/.claude/skills/worktree-manager/scripts/status.sh --project my-project

手动执行：

cat ~/.claude/worktree-registry.json | jq -r '.worktrees[] | "\(.project)\t\(.branch)\t\(.ports | join(","))\t\(.status)"'

清理工作树

参见： reference/cleanup-operations.md，了解完整的清理步骤。

快速清理：

~/.claude/skills/worktree-manager/scripts/cleanup.sh <project> <branch> --delete-branch

参考文件

详细操作请参见：

主题	文件
注册表操作	reference/registry-operations.md
端口分配	reference/port-allocation.md
Agent 启动	reference/agent-launching.md
系统通知	reference/system-notifications.md
脚本参考	reference/script-reference.md
清理操作	reference/cleanup-operations.md
高级工作流	reference/advanced-workflows.md
故障排除	reference/troubleshooting.md

<safety_guidelines>

安全指南

1. 清理之前，检查 PR 状态：

   • PR 已合并 → 可以安全清理所有内容
   • PR 处于打开状态 → 警告用户，确认后再继续
   • 没有 PR → 警告用户存在尚未提交的工作

2. 删除分支之前，在以下情况下进行确认：

   • PR 尚未合并
   • 不存在 PR
   • 工作树中有未提交的更改

3. 端口冲突：如果端口正被非工作树进程占用，请选择其他端口

4. 环境文件：绝不要将 .env 或 .env.local 提交到 git

</safety_guidelines>

<example_session>

示例会话

用户：“为 feature/dark-mode 和 fix/login-bug 创建 2 个工作树”

你：

1. 检测项目：obsidian-ai-agent（来自 git remote）
2. 检测包管理器：uv（找到 uv.lock）
3. 分配 4 个端口：8100 8101 8102 8103
4. 创建工作树：

   git worktree add ~/tmp/worktrees/obsidian-ai-agent/feature-dark-mode -b feature/dark-mode
   git worktree add ~/tmp/worktrees/obsidian-ai-agent/fix-login-bug -b fix/login-bug
   

5. 将 .claude/ 和 .env 复制到每个工作树
6. 安装依赖：(cd <path> && uv sync)
7. 将两个工作树注册到 ~/.claude/worktree-registry.json
8. 启动 Agent：

   ghostty -e "cd ~/tmp/worktrees/.../feature-dark-mode && claude --model opus --dangerously-skip-permissions"
   

9. 报告：

   Created 2 worktrees with agents:
   
   | Branch | Ports | Path | Task |
   |--------|-------|------|------|
   | feature/dark-mode | 8100, 8101 | ~/tmp/worktrees/.../feature-dark-mode | Implement dark mode |
   | fix/login-bug | 8102, 8103 | ~/tmp/worktrees/.../fix-login-bug | Fix login redirect |
   
   Both agents running in Ghostty windows.
   

</example_session>

---

Boris Cherny 工作流集成

iTerm2 通知、Web 会话交接（/teleport）、用于自主会话的 ralph-loop，以及日常工作流协议。

有关 iTerm2 设置、teleport 交接、ralph-loop 模式、终端策略和日常工作流协议，请参阅 reference/advanced-workflows.md。

写入结果旁文件

最后一步，将内容写入 ~/.claude/skill-analytics/last-outcome-worktree-manager.json：

{"ts":"[UTC ISO8601]","skill":"worktree-manager","version":"1.2.0","variant":"default",
 "status":"[success|partial|error]","runtime_ms":[estimated ms from start],
 "metrics":{"worktrees_created":[n],"agents_launched":[n],"worktrees_cleaned":[n]},
 "error":null,"session_id":"[YYYY-MM-DD]"}

如果某些阶段失败但仍产生了结果，请使用状态 "partial"。只有在未生成任何输出时才使用 "error"。