最近两个月我一直在用 AI Agent 并行开发任务。代码产出确实上来了可 git 仓库也被我折腾得不成样子。如果你也在用 Codex CLI、Claude Code 这类工具同时跑三四个任务大概率遇到过这个场景同一个工作目录里Agent A 正在改auth.pyAgent B 觉得这文件太乱顺手帮你重构了然后两边互相覆盖整个分支直接乱成一锅粥。后来我切到了 Git Worktree每个 Agent 一个独立的工作目录问题解决了一大半。但 Worktree 这玩意儿好用归好用命令繁琐、状态难查、清理还麻烦全靠手动管理特别费劲。于是我自己上手写了一个 CLI就是这个 Worktrunk面向并行 AI Agent 工作流的 Git Worktree 管理工具。如果你们团队也在多人多 Agent 共用一个仓库或者你个人喜欢同时让好几个 Agent 分头改代码这篇文章应该能给你不少启发。我不光会讲 Worktrunk 怎么用还会把并行 Agent 工作流里的坑、Worktree 的实现原理、以及我实际踩过的雷都梳理一遍尽量让不同基础的读者都能看明白。1. 为什么并行 AI Agent 工作流离不开 Git Worktree 管理1.1 并行 Agent 开发的实际痛点在 AI Agent 大规模进入日常开发之前Git 的分支切换模型是够用的。开一个功能分支写代码提交切回主分支流程简单直接。但当你同时启动多个 Agent 实例让它们各自处理不同任务时问题就来了。第一个痛点是文件冲突。多个 Agent 如果共享同一个工作目录它们会同时读取当前的代码快照并在运行时基于同一个文件列表做修改。我实测过两个 Agent 同时改同一个文件的情况非常常见。不是说要改同一行才算冲突很多时候 A 改了函数签名B 在调用处还按旧签名生成代码最后合到一起就是编译不过。即便你把任务切得很碎物理隔离也远比逻辑隔离可靠。第二个痛点是上下文污染。Agent 在生成代码前要扫描目录、读关键文件如果目录里已经有别的 Agent 改到一半的代码它会把中间状态当成事实依据。结果就是 A 的临时变量、废弃函数被 B 当作基础设施来用推理结果完全失真。更夸张的一次我同时跑了两个 Agent一个在升级日志库另一个在排查登录报错结果第二个 Agent 认定新的日志库接口才是正确代码围绕旧接口写了半天排查方案纯属自嗨。第三个痛点是分支切换的开销。用git stash加git checkout -b的方式切来切去每次都要处理未提交的变更还要担心 stash 冲突。我见过不少同事切分支前忘记 stash直接把改到一半的代码带到新分支里后续 commit 一混整个历史就乱了。所以结论很直接并行 Agent 工作流需要多个物理隔离的工作目录而 Git Worktree 就是原生支持这个需求的机制。1.2 Git Worktree 能解决什么它本身又带来什么新麻烦Git Worktree 允许你在同一个仓库上挂载多个工作目录每个工作目录对应一个分支对象库和引用库是共享的。这意味着你在 Worktree A 里 commit 的代码在 Worktree B 里立刻可以通过git log看到切换成本几乎为零不用 clone 多份仓库也不占额外磁盘空间对象只有一份。它的原生用法并不复杂三条命令就能覆盖主流程git worktree add ../login-module -b feat/login-module git worktree list git worktree remove ../login-module但当你真的用 Worktree 来支撑并行 Agent 工作流时麻烦就逐一浮现了。第一路径与分支的对应关系需要自己维护。Agent 跑起来之后你得记住哪个目录对应哪个任务、哪个分支、状态如何。任务一多脑子里全是login-module、payment-fix、perf-optimize谁是基于哪个分支拉出来的谁是哪个 Agent 在跑根本分不清。每次进去干活都得先git branch --show-current确认一下。第二清理不干净。git worktree remove在目录不干净的时候会拒绝执行你得先手动处理变更。Agent 中途退出、产生大量临时文件时worktree 目录很容易变成垃圾死角。git worktree list里那些标注prunable的条目你久而久之就懒得理了最后整个.git/worktrees目录越来越臃肿。第三生命周期和 Agent 任务的绑定关系缺失。Agent 任务开始前要建 worktree任务结束后要删除 worktree这些动作如果不自动化人就成了整个链路里最不稳定的环节。你不可能每次都盯着哪个 Agent 退了然后手动去删目录实际执行几次之后就会放弃改成所有任务全塞一个目录里又回到最初的混乱。1.3 Worktrunk 的定位与核心价值Worktrunk 不是一个全新的版本管理方案它做的是把 Git Worktree 封装成更适合 AI Agent 工作流的操作原语。它的定位更像一个调度台让你对每个 Agent 的工作环境有完全的控制和可见性。它解决三个核心问题标准化创建一条命令完成分支名 → 工作目录 → Agent 会话的完整绑定目录命名统一、可读、可预测不再出现../worktree-final-v2这种随机目录。可视化状态随时查看所有 Worktree 的概况包括分支、base、工作区状态、Agent 是否在运行、最近活动时间避免靠记忆管理。可回收生命周期Agent 任务结束时一键清理残留目录自动标记空目录统一清理让仓库长期保持整洁。说白了它让给 Agent 开一个隔离环境这件事从手工活变成了一句话的事。你要做的只是说跑一个任务它负责把房间准备好打扫好。2. Worktrunk 的设计思路与技术选型2.1 核心功能拆解我在设计 Worktrunk 的时候给自己定了个原则它必须比git worktree更懂 Agent 工作流而不是简单包一层。单纯封装命令没有意义真正有价值的是把 Worktree 的生命周期和 Agent 的生命周期绑定起来。功能上主要分成四块worktrunk create创建 Worktree。接收任务名、基础分支、Agent 类型等参数自动生成合法的目录名并完成git worktree add。worktrunk list以表格形式展示所有 Worktree 的状态包括目录位置、分支、base、工作区是否干净、Agent 是否在运行。worktrunk spawn创建 Worktree 后直接在其中启动指定的 AI Agent CLI实现开环境 跑任务一步到位。worktrunk remove / prune安全删除 Worktree。有未提交变更时给出提示支持确认后强制清理prune 则清理所有失效元数据和工作目录。另外还有几个辅助功能比如worktrunk rename用来重命名 Worktree 对应的分支和目录worktrunk archive把完成任务的目录归档而不是直接删除worktrunk refresh用来手动同步 Agent 进程状态。这些功能都遵循同一个原则默认操作安全危险操作必须显式确认。2.2 命令设计与交互模型命令设计上我参照了git和现代 CLI 工具的风格子命令少而明确参数集中输出直观。拿最常用的worktrunk create举例worktrunk create login-module --base main --agent codex这条命令内部做的事情是校验当前仓库没有未提交的变更防止污染 base。基于main创建并切换分支login-module。在工作目录.worktrunks/login-module下执行git worktree add。在 Worktree 的元数据文件中记录 Agent 类型、任务描述、创建时间。如果加了--agent codex和--task 实现用户登录它还会帮忙调用对应 CLI直接在该目录启动 Agent。启动方式很简单就是设置了环境变量的子进程调用Worktrunk 负责把输出透传到你当前的终端。worktrunk spawn --agent codex --base main --task 实现用户登录这里我最在意的设计是默认安全。create 时仓库不干净就拒绝执行remove 时不带--force就不删除有变更的目录。Agent 工作流本身容易产生不可控的变更工具不能成为数据丢失的帮凶。你可以骂它啰嗦但它不会让你后悔。2.3 技术栈选择与实现要点技术栈上我选了 Go。原因有三点编译成单二进制丢到 PATH 里就能用不需要用户装运行时标准库对os/exec、os/signal的支持成熟适合做子进程管理交叉编译方便Windows、macOS、Linux 都能轻松打包。关键实现点有三个。第一与 Git 的交互尽量通过git命令本身而不是直接解析文件。虽然.git/worktrees目录的结构是稳定的但直接操作文件太底层稍微一个版本变化就可能踩坑。用git worktree list --porcelain获取结构化输出用git worktree add/remove/prune管理生命周期兼容性最稳也最符合用户习惯。第二进程管理。spawn 子命令需要把 Agent 进程的 stdout、stderr 透传到终端同时监听 SIGINT 和 SIGTERM保证 CtrlC 时 Agent 和 Worktrunk 都能正常退出。子进程退出后再根据退出码决定是否询问回收 Worktree。这里有个细节如果 Agent 是被信号杀死退出码会是 130 之类的值Worktrunk 会把它和正常退出区分开清理逻辑也不同。第三状态追踪。Worktrunk 会在每个 Worktree 里放一个.worktrunk元数据文件记录 Agent 类型、任务、PID、创建时间。这个文件不算 Git 的受控文件不会影响 Git 操作但能让list输出更丰富的信息。比如你worktrunk list时看到某个目录 Agent 还活着就是靠这个 PID 判断的。3. 实操安装配置与日常使用指南3.1 安装与环境准备Worktrunk 的安装方式很直接就是下载一个二进制放到 PATH 里。我准备了两种方式按习惯选# macOS / Linux 用 Homebrew brew install worktrunk # 或者从 GitHub Releases 直接下载对应平台的压缩包 # 解压后把 worktrunk 文件放到 /usr/local/bin 或者 ~/binWindows 用户直接下载 exe放到一个加入 PATH 的目录里就行。装完以后建议先跑一次worktrunk doctor它会检查三件事当前目录是否是一个 Git 仓库git worktree是否可用常用的 Agent CLIcodex、claude 等是否在 PATH 中接着做一次初始化配置worktrunk config set agent.default codex worktrunk config set dir .worktrunksdir是默认的 Worktree 根目录我建议放在项目根目录下.gitignore里加上它就好。你也可以改成仓库外的路径比如/tmp/worktrunks/myproject但个人建议放在仓库内部这样删除和备份都比较方便。如果你修改了配置记得worktrunk config get确认一下。3.2 常用命令实战我用一个实际场景来演示。假设项目是一个电商后端我同时要跑四个任务用户登录、订单超时处理、性能优化、依赖升级。使用 Worktrunk 的完整流程如下# 1. 先确认当前仓库是干净的 git status --short # 2. 创建登录模块的 Worktree并直接启动 codex agent worktrunk spawn --agent codex --base main --task 实现用户登录包括 JWT 签发与刷新 # 3. 新开一个终端创建订单任务的 Worktree worktrunk create order-timeout --base main --agent codex --task 订单超时自动关闭 cd .worktrunks/order-timeout codex # 4. 定期查看所有 Worktree 的状态 worktrunk listworktrunk list的输出大概长这样名称 分支 基础分支 状态 Agent 最近活动 login-module login-module main 脏 codex 5 分钟前 order-timeout order-timeout main 干净 codex 32 分钟前 perf-optimize perf-optimize release/2.0 干净 claude 2 小时前这个视图让我一眼就能看出哪个 Agent 还在活跃、哪个目录还需要人工处理、哪个分支已经落后于 base 需要合并。实际用下来感觉最大的变化是不用靠记忆管理了打开终端先worktrunk list所有环境情况一目了然。任务结束后进入对应目录把工作收尾提交代码然后运行worktrunk remove login-module如果目录有未提交变更它会列出文件列表并让你确认。确认后执行的是git worktree remove --force的等价操作同时清理元数据和可能存在的远程分支。不带--force时它对脏目录绝对不手软会直接拒绝这就是我前面说的默认安全。3.3 与 AI Agent 结合的典型工作流我觉得 Worktrunk 最有价值的场景是把它接进 Agent 的启动脚本或者自动化工作流里。比如我写了一个小脚本newtask.sh#!/bin/bash # 使用方式./newtask.sh codex 实现商品详情页缓存 worktrunk spawn \ --agent $1 \ --base main \ --task $2然后每次有新任务跑一句./newtask.sh就行。整个流程完全自动化Agent 会在一个全新的分支、全新的目录里开始工作。如果你喜欢用 n8n 或者其他自动化平台也可以在 Webhook 触发时调用worktrunk create把每个任务转变成一条隔离的工作线。比如收到一个 issue就自动为它创建一个 Worktree并挂上对应的 Agent 任务所有变更都隔离在各自目录里互不干扰。这里有一个非常重要的实践Agent 任务结束后不要让 Agent 自己 commit 到当前分支应该把变更留在工作区由人 review 后再提交。原因很简单Agent 生成的 commit message 经常不靠谱而且它会为了完成任务把一堆临时修改混进来。Worktrunk 的spawn在 Agent 退出后不会自动删除 Worktree就是给人工 review 留了余地。4. 实现原理与关键细节解析4.1 Worktree 生命周期管理原理要理解 Worktrunk 的底层逻辑还是得先搞清楚 Git Worktree 本身的机制。每个 Worktree 在.git/worktrees/name目录下保存自己的元数据核心文件有这几个HEAD该 Worktree 当前的提交指针独立维护gitdir指向该 Worktree 元数据目录的绝对路径commondir指向主仓库公共目录的路径普通仓库里的工作目录只有一个index而 Worktree 的HEAD是独立文件但对象库和引用库是共享的。这就是为什么你可以在两个 Worktree 里用不同的分支而不互相干扰但git log又能看到彼此的提交。从本质上讲Worktree 让 Git 从单工作区模型扩展成了多工作区模型这个能力对并行开发几乎是量身定做的。删除 Worktree 的正确方式永远是git worktree remove它会检查该目录是否有未提交的变更和未跟踪的文件。直接rm -rf是很多人踩过的坑因为.git/worktrees/name里的元数据会变成僵尸条目之后git worktree list会一直显示prunable需要git worktree prune来清理。Worktrunk 的 remove 子命令在底层也是调用git worktree remove但在调用前多做了一步检查元数据文件里记录的 Agent PID 是否还活着。如果活着会先提示你避免把正在跑的 Agent 的工作目录直接删掉等 Agent 退出后再清理这个细节帮我避免了好几次误操作。4.2 命名规范与冲突规避Worktrunk 的目录命名规则是.worktrunks/namename默认是分支名的最后一段。分支名里如果包含/比如feature/login-module会生成feature-login-module这样的目录名以保证文件系统的路径合法性。这里有个容易踩的坑分支名里的斜杠、空格、特殊字符在文件系统里不一定合法尤其是 Windows 下的 NTFS 文件系统。所以 Worktrunk 会对名字做一套清洗规则/转成-非字母数字字符一律转成-连续-合并为一个目录名建议全小写避免 macOS 默认大小写不敏感文件系统上的歧义如果目标目录已经存在Worktrunk 会在末尾追加序号-2、-3。这样即使你运行了两次同样的worktrunk create login-module也不会把前一个 Worktree 覆盖掉而是各占一个目录。这个设计是吸取了之前手滑的教训不检查目录就直接worktree add有时候会报目录已存在有时候会把代码写进一个意想不到的地方。4.3 状态检测与清理机制Worktrunk 的 list 输出里状态判断的逻辑是这样的用git status --porcelain判断工作区是否干净用元数据文件里的 PID 判断 Agent 是否在运行用 Worktree 的 HEAD 与 base 分支的差异判断是否有待审查的提交我把一个完整的 Worktree 生命周期定义成了几个阶段创建完成目录建好分支拉出等待任务Agent 运行中spawn 启动 AgentPID 记录在案待审查Agent 退出变更留在工作区待清理人工 review 并提交推送完成已归档执行 remove 或 archive目录清理干净Worktrunk 的prune命令会做两件事一是调用git worktree prune清除 Git 层的失效元数据二是扫描.worktrunks目录下那些已经不在git worktree list里的文件夹提醒你可能还有物理残留需要删除。每周跑一次worktrunk prune仓库状态就能持续保持清爽。5. 常见问题与排查技巧实录5.1 实际操作中踩过的坑坑一直接删除 Worktree 目录导致 prunable 垃圾越积越多。我早期用 Git Worktree 时习惯性地rm -rf删目录删完才发现git worktree list里一坨prunable。用 Worktrunk 之后它强制走git worktree remove或者删除后自动prune这个坑基本堵死了。坑二Agent 在 Worktree 里生成了大量未跟踪文件导致 remove 失败。Codex 这类工具跑任务时会在目录里生成.codex/、日志、临时脚本等文件。git worktree remove遇到未跟踪文件也会拒绝执行。我的做法是先用git clean -nd看看哪些文件是临时文件确认无误后git clean -fd清理再执行 remove。如果你不确定可以用worktrunk remove --keep-untracked先把代码提交到分支工作目录留给人手工处理。坑三多 Agent 同时操作一个 Worktree。有时候你会手滑在两个终端里进入同一个 Worktree 分别跑 Agent这跟你走进同一个场景做两件不同的事是一样的。解决方法是引入锁文件。Worktrunk 在 spawn 之前会在 Worktree 目录写一个.worktrunk.lock里面记录 Agent 的 PID。第二次 spawn 发现锁文件存在时会直接拒绝并提示避免资源争夺。如果是 Agent 异常退出导致的锁残留worktrunk refresh可以强制清除。坑四子模块在 Worktree 里的问题。如果你在仓库里使用了 submoduleWorktree 默认会将 submodule 路径也带过去但 submodule 的 HEAD 状态可能和主仓库的索引状态不一致。好在我日常项目很少用 submodule如果你确实用了建议在 Worktree 里手动跑一次git submodule update --init --recursive。5.2 问题排查速查表现象原因解决方案git worktree list出现prunable目录被直接删除或移动git worktree pruneremove 时提示目录不干净有未提交变更或未跟踪文件处理变更或加--forceworktrunk list显示 Agent 运行中但实际已退出PID 过期进程异常退出worktrunk refresh分支名带斜杠导致目录名异常sanitize 规则冲突worktrunk create --name手动指定在子目录里执行worktrunk命令失败未处于仓库根目录Worktrunk 会向上查找.git但仍建议在根目录操作Windows 下路径过长报错NTFS 路径限制把dir配置到短路径如C:\wtspawn 启动的 Agent 没有输出stdout 未被正确接管检查终端是否支持交互式进程或加--no-tty5.3 一些实用小技巧最后分享几个我日常用得比较多的习惯用worktrunk list --json接一个jq管道可以快速统计每个 Agent 的运行时长对评估任务耗时很有帮助。比如worktrunk list --json | jq .[] | {name, status}。在.bashrc或.zshrc里加一个函数wt() { worktrunk $ }能省不少打字时间。顺手还能加一个wtl指向worktrunk list。如果仓库里有大文件或大量历史对象建议把 Worktree 根目录放到同一个磁盘分区避免跨分区移动带来的额外 IO 开销。虽然 Git 本身是文件级存储但跨分区复制大文件确实慢。定期跑一次worktrunk prune --aggressive把已经完成任务的 Worktree 全部清理掉。一周一次就够了太频繁反而容易误删正在 review 的目录。配合 CI 时可以让流水线在合并主分支后自动对相关的 Worktree 执行worktrunk archive把已经合并的分支从本地清掉避免主分支合并后本地还留着一堆过期分支。个人体会是工具本身不复杂复杂的是把工具和工作流磨合顺。Worktrunk 对我来说最大的价值不是省那几条命令而是它让并行开多个隔离环境变成了一种可重复、可追踪、可清理的标准操作。以前我开一个 Agent 任务要手工做四五个动作现在一句话搞定而且随时知道每个 Agent 在哪个目录里干活、干到什么程度。如果你也在为多 Agent 并行开发的环境管理头疼不妨给它一个机会先从一个小任务开始试试你会感受到那种每个 Agent 都在自己房间里干活的清爽感。