Worktrunk

Worktrunk — Git 工作树管理器，用于 AI 代理 一句话总结：vx worktrunk（别名 vx wt）管理 Git 工作树，以便您可以并行运行多个 AI 代理而不会发生冲突。 worktrunk 是一个使用 Rust 编写的 CLI 工具，专为并行 AI 代理工作流设计。它使 Git 工作树像分支一样易于使用，并具有类似钩子、LLM 提交消息和每个工作树开发服务器等功能。

为什么 AI 代理需要此功能 当在同一个仓库中运行多个 AI 代理（例如 Claude Code、Codex 等）时，它们会发生冲突： 代理 A 修改 src/main.rs 代理 B 修改 src/main.rs → 冲突 解决方案：为每个代理提供自己的工作树（隔离的工作目录）。 主仓库：~/projects/my-app/（主分支） 代理 1：~/projects/my-app.wt/feat-auth/（feat/auth 分支） 代理 2：~/projects/my-app.wt/feat-pay/（feat/pay 分支）

安装（通过 vx） vx install worktrunk vx worktrunk --version # 验证

核心命令 wt switch — 导航工作树 # 创建新工作树并切换到它 vx wt switch -c feat/auth # 切换到现有的工作树 vx wt switch feat/auth # 切换回主仓库 vx wt switch - # 创建并启动 AI 代理的工作树 vx wt switch -c -x claude feat/auth

wt list — 显示所有工作树 vx wt list # 紧凑列表 vx wt list --full # 包括 CI 状态、AI 生成的摘要和 diff 预览

wt merge — 清理合并工作流 vx wt merge # 合并并删除工作树和分支 vx wt merge --rebase # 变基合并 vx wt merge --keep # 合并但保留工作树

wt remove — 清理 vx wt remove feat/auth # 删除工作树 vx wt remove --with-branch feat/auth # 删除工作树和分支

高级功能 PR 检出 vx wt switch pr:123 # 检出 PR #123 到工作树

钩子（自动设置） 在 .worktrunk/hooks.toml 中配置： [post_create] command = "npm install" # 创建时自动安装依赖

[pre_merge] command = "vx run test" # 合并前运行测试

共享工作树之间的构建缓存 # 复制 node_modules/ 到新工作树（跳过冷安装） vx wt switch -c --copy-cache feat/auth

每个工作树的开发服务器（唯一端口） worktrunk 可以为每个工作树分配一个唯一的端口（通过 hash_port 模板过滤器）： # 在 package.json 中： "scripts": { "dev": "next dev -p {{ hash_port 3000 }}" } # 主仓库 → 端口 3000 # feat/auth → 端口 3217（确定性哈希）

典型的 AI 代理工作流

• 主仓库：为代理分配任务

cd ~/projects/my-app echo "添加 JWT 身份验证" > .AITASK

• 为代理 1 创建隔离工作树

vx wt switch -c -x claude feat/auth #（在工作树中，代理自主运行） # 代理修改文件、提交等

• 同时，为代理 2 创建另一个工作树

vx wt switch -c -x claude feat/pay

• 当代理完成时，合并两个工作树

vx wt merge feat/auth vx wt merge feat/pay

vx 集成 worktrunk 由 vx 安装和管理： # 安装 vx install worktrunk # 运行（vx 自动安装如果缺失） vx worktrunk --version vx wt switch -c feat/auth # 更新 vx install worktrunk@latest

命令参考 命令 描述 vx wt switch [分支] 切换到工作树 vx wt switch -c [分支] 创建工作树并切换 vx wt switch -c -x <命令> [分支] 创建并运行命令（例如启动 AI 代理） vx wt switch pr:<号> 检出 PR 到工作树 vx wt list 列出工作树 vx wt list --full 详细列表，包括 CI/LLM 摘要 vx wt merge 合并并清理 vx wt remove [分支] 删除工作树 vx wt remove --with-branch [分支] 删除工作树和分支

AI 代理提示 始终使用 vx wt switch -c 创建隔离环境，然后再进行更改 使用 -x claude 自动在新工作树中启动 AI 代理 使用 vx wt merge 代替手动 git 合并 —— 它处理工作树清理 在 .worktrunk/hooks.toml 中配置钩子以自动安装依赖项 使用 --copy-cache 在工作树之间共享 node_modules/ / target/