Worktrunk：用Git worktree为AI Agent并行开发打造秩序

最近一个月我一直在折腾同一个仓库里同时开好几个 AI Agent 干活Claude Code 改后端Codex CLI 调前端偶尔还要让 Gemini CLI 去查某个历史 bug 的上下文。想法很美好实际一跑就发现 Git 工作区根本不够用一个 Agent 在 main 分支上留了十几处未提交改动另一个 Agent 启动时直接基于这个脏工作区往下写等我想看 diff 时已经分不清哪些改动是谁写的了。后来我把整个工作流切到了 Git worktree再用一个叫 Worktrunk 的命令行工具把 worktree 的生命周期管起来。折腾完这一圈并行 AI 编程才有了真正的秩序。这篇文章就聊聊 Worktrunk 这个工具解决的问题、核心用法以及我在实操中踩过的坑。如果你也在用各类 AI 编程工具同时管理多个任务分支这篇应该能直接帮上忙。1. 这个工具到底解决了什么问题1.1 AI Agent 并行开发最大的隐患是 Git 工作区互相踩踏先说清楚场景。市面上主流的 AI 编程工具Claude Code、Codex CLI、Gemini CLI、Trae CLI它们本质上都是在你当前的 Git 仓库里直接改文件、跑命令、提交代码。单开一个 Agent 很爽但一旦同时跑两个以上问题就来了。最典型的场景是这样的Agent A 接到任务“重构登录模块”它先在 main 分支上创建了自己的功能分支改了十几分钟然后因为某个测试跑挂了它停在那儿等你处理。这时候你干等它很浪费于是又起了 Agent B 去修另一个线上 bug。Agent B 初始化时看到了当前工作区里的未提交改动——这些改动其实是 Agent A 留在功能分支上的——它大概率会困惑甚至直接把 Agent A 的改动一并带进自己的分支提交里。还有一种更隐蔽的问题多个 Agent 都基于同一个 main 分支工作其中一个 Agent 执行了git pull或git merge把其他 Agent 正在修改的文件给覆盖了。你在 IDE 里看一眼代码发现刚改的几行突然变回旧版本但 Git 历史里又查不到是谁干的。这种互相踩踏排查起来非常消耗精力。1.2 为什么最终选型是 Git worktree而不是多 clone 或不停切分支遇到上面的问题其实有三条路多 clone、切分支、worktree。我逐个试过说说实际感受。多 clone 最简单粗暴每个 Agent 一个独立目录互不干扰。但代价很明显每个 clone 都要重新拉一遍对象库几十 GB 的仓库直接翻倍依赖目录也要各自装一遍Node 项目的 node_modules、Python 项目的虚拟环境全得重新来最烦的是远端同步每个 clone 都得单独 push/pull很容易忘记某个 Agent 的改动还没推到远端。不停切分支是另一种思路。用git checkout -b来回切换理论上能在不同分支间快速跳转。但问题在于同一时刻 Git 只允许一个 worktree 处于工作状态。Agent A 在分支 feature/login 上改到一半你切到 feature/bugfix 去干活Agent A 的工作状态就完全中断了。切回来之后之前加载到内存里的中间结果、未提交的临时文件、甚至 IDE 索引全都得重新来。AI Agent 比人类更怕这种上下文丢失。Git worktree 是这两者的中间态也是我最终选它的原因。它允许你在同一个克隆仓库下创建多个工作目录每个目录可以独立 checkout 不同分支彼此之间互不影响。所有 worktree 共享同一个 .git 对象库所以提交、分支、历史记录都是统一的不需要像多 clone 那样反复 push/pull。官方文档的原话是“manage multiple working trees attached to the same repository”翻译成人话就是一套仓库基础设施多个互不干扰的工位。我用一个类比给团队讲这事儿主仓库是总控台worktree 是工位每个 AI Agent 是工人。工人各坐各的工位干活互不抢工具干完活把成果统一交回总控台。总控台只管一个仓库不用复制多份。1.3 Worktrunk 的设计取舍做“状态管理”而不是“又一个 git 封装”既然原生git worktree能创建工位那 Worktrunk 为什么还要存在这是我做这个工具之前反复问自己的问题。原生git worktree的问题在于它只管“创建”和“删除”不管“任务上下文”。我开了一个 worktree 之后过两天回来完全不记得这个 worktree 对应哪个 Agent、在跑什么任务、基线分支是哪个。更麻烦的是清理环节git worktree remove经常因为未提交改动而拒绝执行最后留下一堆.git/worktrees/里的残骸时间一长整个仓库乌烟瘴气。Worktrunk 的核心思路是在原生 Git worktree 之上做一层“任务工作区管理”。它不只是创建目录而是为每个 worktree 关联一份元数据记录任务名、Agent 名称、基线分支、创建时间、最近同步时间。这样你随时能用一条命令查清楚“现在有哪些工位、每个工位在干什么、哪个工位该清理了”。所以它的定位很明确不是替代 Git而是把 Git worktree 包装成一个更适合 AI Agent 并行开发场景的工作流工具。你会看到它的很多命令其实是在背后调用 git但帮你做了参数补全、状态记录、一致性检查。2. 安装与环境准备2.1 依赖清单与版本要求Worktrunk 本身不挑操作系统macOS、Linux、Windows 都能跑但有几个硬性依赖需要注意。第一个是 Git 版本。Worktrunk 严重依赖git worktree命令这个功能在 Git 2.5 引入但早期版本 bug 比较多功能也不全。2.17 之后才算稳定。我建议 Git 版本至少 2.20最好是 2.30 以上因为新版 Git 对 worktree 的路径处理和权限管理都优化了不少。Windows 用户我特别推荐用 Git for Windows 2.35 以上版本有一些路径相关的修复很关键。第二个是 Agent 工具本身。Worktrunk 不绑定具体 AI 编程工具Claude Code、Codex CLI、Gemini CLI、Trae CLI 都可以配合使用。在实际使用中它主要通过环境变量和当前工作目录来向 Agent 传递上下文所以只要你的 Agent 工具支持在指定目录下启动、能读取环境变量基本都能兼容。第三个是可选的如果你打算用到后面说的 MCP Server 集成需要 Python 3.9 或者 Node.js 16取决于你选择哪种启动方式。如果只是命令行使用完全不需要。2.2 三种安装方式怎么选Worktrunk 发布到多个渠道根据自己的环境选一种就行。如果你是 macOS 用户最快的方式是 Homebrewbrew install worktrunk/tap/worktrunk这会自动处理 PATH 和依赖也是我推荐的方式。如果你是 Rust 工具链使用者也可以用 Cargo 安装cargo install worktrunkCargo 安装的优势是版本更新快但需要编译耗时取决于你的机器性能。好处是worktrunk是单二进制文件编译完之后可以直接拷到任意 Linux 服务器上运行很适合放到开发容器或 CI 环境里。Go 用户则可以用go install github.com/worktrunk/worktrunklatest这种方式适合你本来就在 Go 生态里顺手装一下。下载预编译二进制的方案也可以项目 Release 页面上会提供对应平台的压缩包解压后把worktrunk放进 PATH 就行。装完验证一下worktrunk --version能看到版本号就说明装好了。2.3 初始化配置别急着建 worktree安装完之后进入你的项目仓库先跑一遍初始化cd /path/to/your/repo worktrunk init初始化的过程会做三件事第一在.git/worktrunk/目录下创建状态数据库记录所有 worktree 的元数据第二检测当前仓库的分支情况把当前所在分支设为默认基线分支第三生成一份~/.config/worktrunk/config.toml全局配置模板。我的建议是初始化之后先看一眼配置再决定要不要调整。配置文件长这样# ~/.config/worktrunk/config.toml default_base main worktree_root .worktrunk/trees branch_prefix agent default_agent codex sync_mode pull [agents] claude { env { WORKTRUNK_AGENT claude } } codex { env { WORKTRUNK_AGENT codex } } gemini { env { WORKTRUNK_AGENT gemini } }几个关键参数说说我的理解。worktree_root决定 worktree 目录放在哪默认是仓库根目录下的.worktrunk/trees这个路径会自动写入.git/info/exclude不会污染.gitignore也不会误提交。如果你不想让 IDE 索引这些目录可以改成仓库外部的路径比如../.worktrunk-trees。branch_prefix是自动生成分支时的前缀我习惯用agent这样分支名是agent/fix-login这种格式一眼就能看出是 Agent 创建的。default_agent决定不指定--agent参数时按哪个 Agent 的配置注入环境变量。3. 核心命令实操从创建到回收的完整闭环3.1 为 Agent 创建独立工位初始化完成后就可以为你的 AI Agent 开一个独立工位了。我用一个实际例子演示。假设我准备让 Codex CLI 去重构登录模块任务代号叫fix-login。执行worktrunk create --name fix-login --base main --agent codex执行过程会输出类似这样的信息worktree created at .worktrunk/trees/fix-login branch: agent/fix-login base: main task: fix-login agent: codex metadata written to .git/worktrunk/fix-login.json这条命令背后其实做了几件事检查main分支是否存在且有agent/fix-login冲突用git worktree add -b agent/fix-login .worktrunk/trees/fix-login main创建 worktree把任务元数据存到状态数据库最后写入环境变量文件到 worktree 目录。创建完成之后你会获得一个全新的目录.worktrunk/trees/fix-login这个目录干净、隔离、可以自由切换分支。等你进入目录启动 Agent 时Worktrunk 会自动把WORKTRUNK_TASKfix-login、WORKTRUNK_AGENTcodex、WORKTRUNK_BASEmain这组环境变量注入进去Agent 启动后就能感知到自己处在哪个任务中。用一条命令直接在该 worktree 内启动 Agent 也是可以的worktrunk exec fix-login -- codex这会在指定的 worktree 目录下启动 Codex CLI同时注入上述环境变量。好处很明显你不用手动cd进去也不会因为cd错了目录而把命令跑在错误的工作区里。如果你同时开了五六个 worktree这种“显式指定目标”的执行方式能避免大量误操作。3.2 查看和管理多个 worktree并行任务一多“有哪些工位在跑”这个信息就成了刚需。用worktrunk list查看所有 worktree 的状态worktrunk list输出会以表格形式呈现大致长这样NAME BRANCH BASE AGENT STATUS LAST SYNC fix-login agent/fix-login main codex clean 2 min ago add-rag agent/add-rag main claude dirty 40 min ago fix-typo agent/fix-typo main gemini clean 1 hour ago这里的STATUS列是 Worktrunk 额外做的状态检测它检查 worktree 工作区是否干净有没有未提交改动、未推送提交、未合并的冲突。这比直接跑git status高效得多因为你不用手动进到每个目录里看。worktrunk status name可以看单个 worktree 的详细信息包括分支与基线分支的相对位置落后多少个提交、超前多少个提交都直接列出来。如果要在某个 worktree 里跑一条命令又不想进入目录用execworktrunk exec fix-login -- git status worktrunk exec add-rag -- npm test3.3 一键同步主分支rebase 前先确认干净并行开发最大的问题之一是分支漂移。你的 Agent 在agent/fix-login分支上改了三天main 分支早就被别人推进了一大截。这时候你需要把 main 的新提交同步到 Agent 的工作分支里。Worktrunk 提供worktrunk sync命令worktrunk sync fix-login这条命令做的是记录当前 worktree 的未提交状态执行一次git fetch origin然后尝试把当前分支 rebase 到最新的 main 上最后恢复未提交的改动。默认用 rebase 而不是 merge是为了保持 Agent 生成的提交历史是线性的后续合并回 main 时更干净。但这里有个很重要的安全机制如果 worktree 工作区有未提交改动sync 会先检查这些改动是否与即将 rebase 的提交冲突。如果冲突它会停下来不会强制 rebase因为这个场景下自动处理风险太大——AI Agent 生成的未提交改动往往是一大坨中间状态盲目 rebase 会把上下文搞得一团糟。如果你有一堆并行的 worktree想一次性全部同步可以跑worktrunk sync --all它会逐个 worktree 同步任何一个失败都不会影响其他的。这个sync --all是我每天早上开工前的例行操作跑一遍就能知道哪些工位落后了、哪些有冲突需要人工介入。3.4 任务收尾与清理策略Agent 任务完成之后最重要的一步是把 worktree 收回保持仓库整洁。Worktrunk 的清理流程和 git 原生的不太一样。假设fix-typo这个任务已经合并到 main不再需要独立工位worktrunk rm fix-typo这一步会先把该 worktree 的分支与 main 合并情况做个检查。如果发现分支还有未合并的提交它会询问你是强制删除还是要先合并。只有确认后它才会执行git worktree remove并从状态数据库里删除元数据。还有一个我特别喜欢的命令是worktrunk pruneworktrunk prune它会扫描所有注册的 worktree发现某个目录已经被手动删除了或者某个 worktree 的元数据与 Git 状态不一致就自动清理掉。这个命令能解决一个非常恶心的场景某天你手动在文件管理器里删掉了一个 worktree 目录过几天git worktree list会显示一个不存在的路径每次操作都报错。prune能把这些残骸一次性扫干净。对于不再需要但又不确定是否删干净的任务可以先把 worktree 搁置而不是直接删除worktrunk archive fix-loginarchive会把 worktree 从主状态里移除但保留目录和分支。这样你可以在需要时用worktrunk restore fix-login把它恢复回来。这比直接删除安全得多尤其适合那种“Agent 任务说做完但其实还有尾巴”的情况。3.5 用配置文件管理多个 Agent 的默认模板如果你经常在同一个仓库里用多个不同的 Agent 开不同类型的任务可以进一步定制默认模板。 Worktrunk 支持在仓库根目录下放一个.worktrunk/project.toml内容如下# .worktrunk/project.toml default_base develop worktree_root ../.worktrunk-trees-freelance branch_prefix freelance [agents] claude { env { WORKTRUNK_AGENT claude, REVIEW_STYLE strict } } codex { env { WORKTRUNK_AGENT codex } } [hooks] post_create echo created ${alias}这个配置适合那种“一个仓库对应多个项目任务”的场景。你可以为每个任务分组设置不同的 worktree 根目录、默认基线分支、Agent 环境变量。后面的hooks部分支持在特定事件后执行自定义命令比如创建 worktree 之后自动打开编辑器、自动装依赖。配置文件的优先级是项目级的.worktrunk/project.toml覆盖全局的~/.config/worktrunk/config.toml命令行参数优先级最高。这个设计让我在切换项目时不需要频繁改全局配置。4. 与主流 AI 编程工具链的集成方式4.1 在 Claude Code 里接住环境变量Claude Code 是目前我主力使用的 Agent 工具它在启动时会读取当前目录下的环境变量也会执行目录中的配置文件来获得上下文。Worktrunk 的价值在这里体现得特别明显。最基础的用法是直接进入 worktree 启动 Claude Codeworktrunk exec fix-login -- claude启动后Claude Code 运行在fix-login这个独立工作区里所有文件读取、文件编辑、命令执行都被限制在这个目录内。配合 Worktrunk 注入的WORKTRUNK_TASKfix-loginClaude Code 的提示词里可以自然带上任务上下文不会把别的工位的代码改动误认为是当前任务的一部分。如果你想更深度集成可以写一个自定义系统提示词让 Agent 主动查 task id你在 worktrunk 工位 {{WORKTRUNK_TASK}} 中工作。 当前基线分支是 {{WORKTRUNK_BASE}}。 任务结束后请检查当前分支提交并执行 worktrunk status。这样 Agent 在收尾时会主动调用worktrunk status检查自己有没有遗漏未提交的内容整个循环很自然。4.2 Codex CLI / Gemini CLI 的落地用法Codex CLI 的逻辑和 Claude Code 类似也是基于当前目录操作。直接配合的方式同样是worktrunk execworktrunk exec add-rag -- codex不过我后来发现一个更顺手的模式不通过worktrunk exec启动而是让 Agent 工具自己感知 worktree。具体做法是在.worktrunk目录放一个agent.md文件里面写上任务说明、分支命名规范、同步注意事项。Claude Code 默认会读取CLAUDE.mdCodex CLI 默认会读取AGENTS.md把这些约定放到 worktree 根目录下Agent 一启动就能看到。# AGENTS.md 本项目使用 Worktrunk 管理并行任务工作区。 当前任务{{WORKTRUNK_TASK}} 基线分支{{WORKTRUNK_BASE}} 操作规范 1. 不要修改其他 worktree 目录中的文件。 2. 提交前先运行 worktrunk status 确认分支状态。 3. 如果发现与主分支冲突使用 worktrunk sync task 同步。这个方法的好处是每个 Agent 都能读到当前工位的上下文不需要额外记忆或文档。4.3 更进一步把 worktrunk 以 MCP Server 暴露给 Agent如果你用的是支持 MCPModel Context Protocol协议的 Agent 工具比如新版 Claude Code、支持 MCP 的 Trae CLI 等还可以把 Worktrunk 封装成 MCP Server让 Agent 在对话中直接调用 worktree 管理能力。MCP Server 本质上是一个 JSON-RPC 服务Worktrunk 暴露几个核心工具给 Agent 调用大致接口设计如下{ tools: [ { name: create_worktree, description: 创建新的并行工作任务区, inputSchema: { type: object, properties: { name: { type: string }, base: { type: string } }, required: [name] } }, { name: list_worktrees, description: 列出所有工作任务区及状态 }, { name: sync_worktrees, description: 同步指定任务区到最新基线 } ] }这样设计之后Agent 在规划任务时就能自动调用create_worktree为自己创建独立工作区任务完成后调用list_worktrees确认状态再调用sync_worktrees同步最新代码。这一套下来整个“创建工位 - 干活 - 收尾 - 清理”的流程就不需要人手动干预了。这是 Worktrunk 后续最值得关注的方向之一等于把 Git 工作流本身也变成 Agent 可调用的工具链。5. 常见问题与排查技巧实录5.1 分支已被占用不能在同一个分支开两个 worktree这是使用 Worktrunk 时最常遇到的报错。执行worktrunk create --name foo时如果自动生成的分支名和别的 worktree 的分支撞了Git 会直接拒绝fatal: agent/foo is already used by worktree at .worktrunk/trees/other这个报错的根本原因是 Git worktree 的硬性限制一个分支在同一时间只能被一个 worktree 检出。这也是为什么 Worktrunk 默认在创建时带一个随机后缀降低冲突概率。但如果你手动指定了--name还是可能撞上。解决思路不是去改 Git 规则而是利用 Worktrunk 的元数据查询worktrunk list先看哪个 worktree 占用了目标分支如果那个工位已经废弃直接删掉腾出分支如果还在用就换一个任务代号。实际上我建议在一个空目录里创建 worktree 作为“临时工位”别把分支名和任务名绑得太死这样并行任务多的时候灵活得多。5.2 删除后残留状态worktree prune 的正确时机还有一个高频问题是在手动删除了 worktree 目录后Git 仍然认为该 worktree 存在。典型报错是error: branch agent/foo is checked out at .worktrunk/trees/foo这时候执行git branch -D agent/foo会被拒绝因为 Git 认为这个分支还在被一个 worktree 使用。正确的处理方式是先执行worktrunk prune它会把已经不存在的目录失效化并清理元数据。然后你再去git branch -D agent/foo就没有阻碍了。如果你用了 Worktrunk 之后还是习惯手动去删目录一定要记得跑worktrunk prune这一步是安全删除分支的前提。5.3 Windows 路径过长与权限问题Windows 上使用 worktree 最头疼的问题是路径长度。默认 worktree 路径是.worktrunk/trees/任务名如果仓库本身在C:\Users\你的名字\Projects\long-project-name\这种长路径下叠加起来很容易超过 Windows 经典 260 字符路径上限。我踩过一次这个坑起因是任务名太长Worktrunk 的 worktree 路径超过了限制导致里面跑 Git 命令一直报错提示“文件名对目标文件夹可能过长”。解决办法有两个。第一在config.toml里把worktree_root改到短路径比如C:\wt\或者项目盘符根目录下的_wt第二开启 Windows 长路径支持在注册表里把LongPathsEnabled设为 1并确保 Git for Windows 也启用了长路径。我两个方案都做了但更推荐第一种因为它不依赖系统配置对团队协作环境更友好。5.4 sync 冲突并行合并的“暂停-通知”机制worktrunk sync --all在执行时如果多个 worktree 同时往 main 上 rebase很可能会产生冲突。这是并行开发中绕不开的坎。某个 worktree sync 失败时Worktrunk 会把该 worktree 标记为conflict状态然后继续处理其他 worktree不会因为一个冲突卡住整个同步流程。处理冲突的方式是worktrunk exec fix-login -- git status进入冲突现场看哪些文件有冲突标记然后手动解决。但这里有个经验不要让 AI Agent 自己盲目解决 rebase 冲突。Agent 对“两个分支各自改了什么”的理解有限自动 merge 经常会把代码弄成四不像。我的流程是先把冲突文件列表发给 Agent让它分析一下两边改动意图然后我手工决定如何合并或者干脆放弃 rebase、改用 merge 方式保留两边历史。你可以设置sync_mode merge来让 Worktrunk 默认用 merge 而不是 rebase但这会牺牲提交历史的线性度。需求不同自己取舍。5.5 一个特别容易被忽略的问题worktree 里跑构建和依赖最后一个提醒可能很反直觉worktree 虽然让 Git 层面完全隔离了但很多工具链并没有隔离。特别是依赖目录比如 Node 项目的node_modules、Python 项目的.venv这些是按目录存的每个 worktree 都要各自安装一遍。假设你有三个 worktree每个跑一遍npm install轻轻松松多出两三个 GB 的磁盘占用。更头疼的是如果三个 worktree 里的package-lock.json版本不一样同一个依赖可能会被安装三个版本缓存一乱构建结果就会变得不可复现。我的处理方式是把缓存目录和产物目录统一指到 worktree 外面。比如 Node 项目里设置NODE_MODULES_CACHE、Python 里用虚拟环境复用同时把 worktree 目录加入 IDE 的忽略列表避免 IDE 索引重复扫描这些目录。这些细节不解决worktree 的磁盘和性能优势就会被抵消掉。最后分享几个实战小心得用 Worktrunk 跑了一个多月并行 AI Agent 工作流之后我最大的体会是这个工具最大的价值不是省了那几条命令而是它让“并行”这件事变得可管理、可追溯。以前我开三个 Agent 心里是慌的不知道谁改了什么、谁是哪个分支、哪些提交是哪个任务产生的。现在worktrunk list一列所有工位状态一目了然每个 Agent 在哪儿、在干什么、有没有同步问题一眼就看清楚了。几个具体的实战经验分享给大家第一worktree 目录我强烈建议放仓库外部虽然默认在.worktrunk/trees看起来方便但很多工具会自动扫描仓库里所有子目录放外面能少很多干扰。第二每天早上全量sync --all是个好习惯它能在冲突变复杂之前给你一个低成本的解决窗口。第三如果你同时管理多个 Agent建议把 AGENTS.md 写进仓库并让所有 worktree 共用这样每个工位启动时都知道自己是干嘛的。最后再分享一个小技巧在 shell 提示符里把当前 worktree 名称显示出来。Worktrunk 可以输出一个WORKTRUNK_ACTIVE环境变量你在.bashrc或.zshrc里配置一下让 PS1 显示当前所在的工位名字。这样你就永远不会在错误的目录里执行命令了——这是并行工作流里最微不足道却也最关键的防呆设计。