Worktrunk：AI 并行开发 Git Worktree 管理器完全指南

§1 学习目标

完成本文档后，你将能够：

• ✅ 理解 Worktrunk 的核心定位与设计理念
• ✅ 掌握 Worktrunk 的四个核心命令（switch/list/merge/remove）
• ✅ 熟练使用 Hooks 实现自动化工作流
• ✅ 配置 LLM Commit Messages 自动生成提交信息
• ✅ 使用 Merge Workflow 一键合并分支
• ✅ 启动多个 AI Agent 并行开发
• ✅ 调试和排查 Worktrunk 问题
• ✅ 为 Worktrunk 贡献代码

§2 项目概述

2.1 什么是 Worktrunk？

Worktrunk（官方仓库：max-sixty/worktrunk）是一个 Git Worktree 管理 CLI 工具，专门为并行运行 AI Agent 而设计。

官方描述：

Worktrunk is a CLI for git worktree management, designed for running AI agents in parallel. Worktrunk’s three core commands make worktrees as easy as branches. Plus, Worktrunk has a bunch of quality-of-life features to simplify working with many parallel changes, including hooks to automate local workflows.

翻译：Worktrunk 是一个用于 Git Worktree 管理的 CLI，专门为并行运行 AI Agent 设计。Worktrunk 的三个核心命令让 Worktree 使用起来和普通分支一样简单。此外，Worktrunk 还有大量提升体验的功能，简化多并行变更的工作流程，包括 Hooks 来自动化本地工作流。

2.2 为什么需要 Worktrunk？

Git Worktree 的痛点

Git 原生的 Worktree 命令 UX 很繁琐。即使是创建一个新 Worktree 这样的小任务，也需要输入三次分支名：

git worktree add -b feat ../repo.feat
cd ../repo.feat

Worktrunk 的解决方案

Worktree 通过分支名寻址，路径由可配置模板自动计算：

2.3 核心数据

Stars:     4,000 (4k)
Forks:     129
Watchers:  5
贡献者:    35 人
提交数:   3,267 次
分支数:    62 个
标签数:    95 个
发布版本:  94 个
最新版本:  v0.33.0 (2026-03-27)
许可证:    MIT OR Apache-2.0
语言:      Rust 99.4%

2.4 项目时间线

§3 核心命令详解

3.1 wt switch — 切换/创建 Worktree

基本用法

# 切换到已存在的 worktree
wt switch feat

# 创建并切换到新 worktree
wt switch --create feature-auth
wt switch -c feature-auth

创建并运行命令

# -x 运行命令（agent），-c 创建分支
wt switch -x claude -c feature-a -- 'Add user authentication'

这会：

1. 从 main 创建新分支 feature-a
2. 创建 worktree
3. 在新 worktree 中启动 Claude

参数说明

3.2 wt list — 列出 Worktree

基本用法

# 简洁列表
wt list

# 完整模式（显示状态、提交信息、CI）
wt list --full

输出示例

Branch       Status  HEAD±  Remote⇅  Commit  Age    Message
@ feature-auth  +     ↑+27   -8     ↑1     4bc72dc9  2h    Add authentication module
^ main           ↕     ⇡     ⇡1     0e631add  1d    Initial commit

○ Showing 2 worktrees, 1 with changes, 1 ahead, 1 column hidden

状态符号说明

3.3 wt merge — 合并分支

基本用法

# 合并到 main
wt merge main

Merge Workflow 自动执行

1. 生成提交信息（LLM）
2. 提交变更
3. Rebase 或 merge 到目标分支
4. 清理（删除 worktree 和分支）

3.4 wt remove — 清理 Worktree

基本用法

# 删除当前 worktree（需先切换到其他）
wt remove

# 删除指定的 worktree
wt remove feature-auth

§4 AI Agent 并行开发

4.1 核心概念

AI Agent（如 Claude Code、Codex）可以处理更长的任务而不需要监督，因此同时管理 5-10+ 个并行的 Agent 成为可能。

Git 的原生 Worktree 功能给每个 Agent 自己的工作目录，这样它们不会互相踩踏对方的变更。

4.2 启动多个 Agent

# 并行启动三个 Agent
wt switch -x claude -c feature-a -- 'Add user authentication'
wt switch -x claude -c feature-b -- 'Fix the pagination bug'
wt switch -x claude -c feature-c -- 'Write tests for the API'

4.3 配置 post-start Hooks

配置 post-start Hooks 来自动化设置（安装依赖、启动开发服务器等）：

# .worktrunk.yaml
hooks:
  post-start:
    - command: npm install
    - command: npm run dev

§5 Hooks 自动化

5.1 支持的 Hook 类型

5.2 配置示例

# .worktrunk.yaml
hooks:
  post-create:
    - command: npm install
      description: Install dependencies
  
  post-switch:
    - command: echo "Switched to $(wt list --current)"
      description: Log switch
  
  post-merge:
    - command: npm test
      description: Run tests after merge

5.3 自动化开发服务器

每个 worktree 有唯一端口：

hooks:
  post-create:
    - command: npm run dev -- --port {{ hash_port }}
      description: Start dev server on unique port

§6 LLM Commit Messages

6.1 功能说明

Worktrunk 可以使用 LLM（通过 OpenAI/Anthropic API）自动从 diff 生成有意义的提交信息。

6.2 配置

# .worktrunk.yaml
llm:
  provider: anthropic  # 或 openai
  model: claude-sonnet-4-5
  auto-commit: true

6.3 使用

# 自动生成并提交
wt merge main
# 输出：
# ✓ Generating commit message... (2 files, +53)
# Add authentication module

§7 安装与配置

7.1 安装方式

Homebrew（macOS & Linux）

brew install worktrunk
wt config shell install

Cargo

cargo install worktrunk
wt config shell install

Arch Linux

paru worktrunk-bin
wt config shell install

7.2 Shell 集成

安装后运行：

wt config shell install

这允许命令自动切换目录。

7.3 配置文件

Worktrunk 使用 .worktrunk.yaml 作为配置文件：

# .worktrunk.yaml
template: "{repo}.{branch}"  # worktree 路径模板
default-branch: main           # 默认分支
hooks:
  post-create:
    - command: npm install

llm:
  provider: anthropic
  model: claude-sonnet-4-5

§8 进阶功能

8.1 Interactive Picker

交互式选择器，支持实时预览 diff 和日志：

wt switch --interactive
# 或简写
wt switch -i

8.2 PR/MR Checkout

直接跳转到 PR 的分支：

wt switch pr:123      # GitHub PR
wt switch mr:456       # GitLab MR

8.3 Copy Build Caches

在 worktrees 之间共享构建缓存：

# .worktrunk.yaml
copy-build-caches:
  - target/
  - node_modules/
  - .venv/

跳过冷启动。

8.4 wt list –full

完整模式显示：

• CI 状态
• 每个分支的 AI 生成摘要

8.5 Dev Server Per Worktree

每个 worktree 有唯一端口（使用 hash_port 模板过滤器）。

§9 工作流示例

9.1 PR 工作流

# 1. 创建特性分支
wt switch --create feature-auth

# 2. Agent 在此分支工作
# ...

# 3. 提交、推送、创建 PR
wt step commit
gh pr create

# 4. PR 合并后自动清理
# （PR 合并后）
wt remove

9.2 本地合并工作流

# 1. 创建特性分支并切换
wt switch --create feature-auth

# 2. Agent 在此分支工作
# ...

# 3. 自动生成提交信息、rebase、合并、清理
wt merge main

9.3 并行 Agent 工作流

# 并行启动多个 Agent
wt switch -x claude -c feature-auth -- 'Add authentication'
wt switch -x claude -c feature-api -- 'Create API endpoints'
wt switch -x claude -c feature-ui -- 'Build dashboard'

# 每个 Agent 在独立 worktree 中工作
# 互不干扰

# 完成后的合并
wt merge main  # 对每个分支依次执行

§10 项目结构

10.1 仓库结构

10.2 核心源文件

§11 常见问题

Q1：Worktrunk 和 git-worktree 有什么区别？

Q2：Worktrunk 支持哪些 Git 平台？

Q3：如何调试 Worktrunk？

# 查看详细输出
wt switch -vvv feat

# 查看当前配置
wt config show

# 查看所有 worktree
wt list --verbose

Q4：Worktrunk 和 Zellij 集成？

Worktrunk 支持在 Zellij（终端多路复用器）中显示多个 Agent：

# 使用 Zellij 作为终端复用器
wt switch -x 'zellij attach -c' -c feature-a

Q5：如何贡献 Worktrunk？

1. ⭐ Star 仓库
2. 反馈问题（哪怕是小摩擦或不完美的用户体验）
3. Fork 并提交 PR

Q6：支持 Windows 吗？

部分支持。Windows 支持仍在完善中，主要通过 WSL 使用。

§12 术语表

§13 总结

13.1 核心价值

13.2 适用场景

13.3 项目信息

• Stars：4k
• Forks：129
• 贡献者：35 人
• 最新版本：v0.33.0 (2026-03-27)
• 许可证：MIT OR Apache-2.0

13.4 相关资源

文档版本 1.0 | 撰写日期：2026-03-31 | 基于 v0.33.0 (2026-03-27) | Stars: 4k ⭐