一直用 Claude Code 和 Codex CLI 跑并行任务的同学应该都经历过这种混乱同一份仓库里开了三个终端Agent A 在改src/api/下的路由Agent B 在动src/utils/的公共函数Agent C 在吭哧吭哧重构测试用例。前十分钟大家相安无事等到各自跑完准备提交时报错、冲突、互相覆盖一片狼藉。我一开始的做法是让 Agent 各开一个分支改完再合并可实际操作起来同一个工作目录里分支切换本身就是噩梦——未提交的改动会被 Git 拦下改了 A 分支忘了 B 分支的存留代码Stage 区域的文件张冠李戴。后来我把目光投向 Git Worktree一份仓库在多个目录下同时检出多个分支互不干扰。这个特性对我来说不是新知识但真正让我下决心自研工具的是裸用git worktree命令时那种什么都要自己记的痛苦——worktree 挂在哪个路径、对应什么任务、基于哪个基线分支、agent 干活干到一半的状态记录、用完怎么清理全靠人脑维护一旦 Session 一多必然出错。于是就有了今天想聊的主角Worktrunk。一个面向并行 AI Agent 工作流的 Git Worktree 管理 CLI核心思路是把一次 Agent 任务映射为一个隔离的 worktree 工作区用命令行工具统一管理任务生命周期。本文不打算只丢一堆命令手册我会从实际场景出发讲讲为什么需要它、Git Worktree 有哪些底层行为容易被忽略、我在设计 Worktrunk 时的取舍以及踩过的一些坑。如果你是重度使用 AI 编程 CLI 的开发者或者正在搭建多人/多 Agent 协作流程这篇文章应该对你有用。1. 多 Agent 并行开发的真实痛点不是工具不够多而是隔离不够彻底先说一个我自己的实测案例。上个月接了个中大型项目业务逻辑堆在三个模块里进度压得紧。我的方案是用 Claude Code 开两个会话Codex CLI 开一个会话让它们并行处理三个相对独立的 feature。乍一听合理但真正跑起来问题一个接一个地蹦出来。1.1 同一工作目录下的分支切换陷阱最开始我让三个 Agent 工作在同一份代码目录约定各用各的分支。问题在于Agent 之间可能间隔几秒到几分钟轮流修改文件而git switch的默认行为是工作区必须干净才能切分支。Agent A 在分支 feature/login 上改了三个文件还没来得及提交Agent B 在分支 feature/export 上干完活想切回来查看——被 Git 直接拒绝。如果强制用git switch -f或者 stash轻则丢掉上下文重则把 Agent A 的半成品代码直接冲掉。有人会说让 Agent 每步都提交不就行了但 AI Agent 的工作模式和人有本质区别。人写代码会主动分阶段提交Agent 却常常一口气改完一坨文件才停下来。它不像人那样有这个节点可以安全提交的意识你催它频繁提交反而会污染提交历史产出大量半成品 commitreview 的时候极其痛苦。1.2 多 Agent 并发在同一仓库时的隐式耦合哪怕分支分开了只要工作目录是同一个隐式耦合依然存在。举例Agent A 改了package.json加了新依赖Agent B 的工作目录恰好也缓存着旧的package.json它运行测试时要么找不到包要么被版本冲突炸得一脸懵。再比如 IDE 的文件监听器watcher多个终端同时触碰同一目录索引重建、lint 缓存失效、热更新错乱这些都是真金白银的时间损耗。我统计过一周的浪费时间因为目录冲突和分支切换导致的重跑、恢复、沟通成本平均每天多花一到两个小时。这个数字在并行 Agent 增多时非线性上涨——3 个 Agent 还能靠人工压住5 个以上直接失控。1.3 多个 Agent 并行时为什么需要的是完整可独立工作的环境后来我意识到Agent 并行和人并行需要的隔离粒度不一样。人写代码同一目录下开两个终端分属不同分支已经很常见因为人脑会记住这个终端现在在哪个分支这一段代码属于哪个任务。Agent 没有这种全局记忆它只知道自己被塞进一个目录、被告知一个任务。如果这个目录还带着上一轮 Agent 留下的脏改动、未合并的分支、奇怪的依赖状态Agent 的每一步都可能被这些残存状态误导。所以多 Agent 真正需要的是一个干净、独立、可随时销毁重建的环境。Git Worktree 恰好是这种环境的最小实现不同目录映射同一仓库不同分支互不干扰消灭即走。但 Git 原生命令只给了创建/删除的 API没有给按任务管理 worktree 生命周期的上层抽象——这就是 Worktrunk 存在的理由。2. Git Worktree 的底层行为拆解理解这些你才能信任这个工具Worktrunk 的根本是 Git Worktree所以我把这个底层机制掰开揉碎讲一遍尤其是那些不常用就发现不了的行为。理解这些后面用 Worktrunk 时才不会心里没底。2.1 worktree 的核心机制一份仓库多个工作目录Git Worktree 允许你在同一个仓库里同时 checkout 多个分支每个分支对应一个独立目录。它的核心实现是原始克隆的目录保留一份完整的.git目录而新增的 worktree 通过一个.git文件指向主仓库的 git 目录实际的HEAD、索引、objects、refs 全部共享但工作区和索引文件各自独立。你可以用下面的命令感受一下# 在 main 分支上 git worktree add ../feature-login -b feature/login # 在 ../feature-login 目录里你可以自由 checkout、commit、push git worktree list输出会类似/Users/me/project main /Users/me/project-feature-login feature/login每一个 worktree 有独立的HEAD、索引和暂存区。也就是说你在 A 目录git add的文件不会跑到 B 目录里去A 目录的未提交修改也不会阻塞 B 目录的git switch。2.2 共享 refs 带来的两个重要约束ReFs 和对象数据库是共享的由此衍生出两个关键约束第一同一时间同一个分支只能在一个 worktree 中被检出。如果你在主目录main分支上再想用另一个 worktree 检出main分支Git 会直接拒绝。这不是一个 bug而是保护机制——同一个分支如果在两个目录同时操作历史会变得不可收拾。这意味着你设计任务工作流时必须确保每个任务对应独立分支Worktrunk 也是围绕这个约束设计的。第二worktree 里做的 commit 是全仓库可见的 refs 更新。你在某个 worktree 里提交了feature/login的三个 commit主仓库里同样能看到这个分支。这在多 Agent 场景下是个双刃剑——好的一面是其他 worktree 可以切到该分支查看代码坏的一面是如果两个 Agent 同时 push 同一个分支依旧会冲突。所以 Worktrunk 会强制给每个任务分配独立分支从源头规避这个问题。2.3 清理 worktree 的正确姿势与孤儿 worktree的成因删除 worktree 不是按 Delete 键把目录删了就行。假设你把整个目录用rm -rf删除了Git 的.git/worktrees里还留着这个 worktree 的元数据git worktree list会显示一个已不存在但未清除的条目后续git worktree add有时还会误报路径冲突。正确的删除方式git worktree remove path # 如果该 worktree 有未提交的改动或 untracked 文件需要先清理或加 --force git worktree pruneprune的作用是清除 Git 内部记录的、物理目录已经不在的 worktree 元数据。这个命令在手动删除目录后必不可少。2.4 worktree 与配置文件、hooks 的隔离边界很多人在.git/config里配了 user.name、remote URL 等全局设置但这些对 worktree 并不是完全共享的。简单来说worktree 共享仓库级的 config 文件但每个 worktree 可以额外维护自己的config.worktreeGit 2.20 支持这意味着你可以给不同的 worktree 设置不同的remote.origin.url、branch.xxx.remote甚至 core 配置。hooks 则是所有 worktree 共享同一个.git/hooks目录这点需要注意——如果你的 hook 依赖路径或当前目录它会在多个 worktree 里同时触发路径相关的脚本极容易踩坑。3. Worktrunk 的核心设计将Agent 任务映射为Worktree 命名空间我对 Worktrunk 的定位是一个按 Agent 任务管理 Git Worktree 生命周期的命令行工具核心不在 Git 操作本身而在于任务与工作区的映射关系。它把 Git Worktree 从通用机制变成了 AI Agent 工作流的一等公民。3.1 命令设计的三个原则在设计命令时我给自己定了三个原则第一命令必须按任务语义命名而不是按 Git 操作命名。用户不关心git worktree add的参数细节用户只关心我想让 Agent A 开始做登录功能。所以 Worktrunk 的核心命令是worktrunk create、worktrunk list、worktrunk switch、worktrunk destroy而不是add、remove这类底层词汇。第二操作必须幂等。Agent 任务经常要重跑create重复执行时如果任务已经存在就应该稳定返回已有 worktree 的路径而不是报错或新建一个重复的目录。第三必须支持上下文恢复。Agent 中途可能会断线、超时、被杀掉工具需要能从命令行参数、配置文件或环境变量里恢复此前的工作状态。3.2 目录命名约定让 Agent 任务天然可识别Worktrunk 默认的 worktree 路径是.worktrunk/{agent-id}/{task-slug}放在仓库根目录下的.worktrunk文件夹中。agent-id是 Agent 的名称或编号如claude-code-1、codex-2task-slug是任务的短链标识如fix-login-redirect。例如worktrunk create --agent claude-code-1 --task fix-login-redirect --base main会生成一个路径为.worktrunk/claude-code-1/fix-login-redirect的工作区并自动基于main创建分支agent/claude-code-1/fix-login-redirect。同时 Worktrunk 会把任务元数据写进一个本地 JSON 状态文件默认.worktrunk/state.json记录任务的 base 分支、创建时间、最后活动时间、Agent ID 等。这个命名约定的好处是人眼看到路径就知道是哪个 Agent、在做什么任务极大降低了多任务并行时的识别成本。而且.worktrunk默认加入.gitignore不会污染仓库。3.3 核心生命周期创建、查看、切换、销毁Worktrunk 的命令体系围绕任务生命周期展开我不建议做得太复杂核心就四类# 创建任务工作区 worktrunk create --agent id --task slug [--base branch] # 查看所有任务工作区及其状态 worktrunk list [--json] # 切换到某个任务工作区CD 到对应目录 worktrunk switch task-slug # 销毁任务工作区默认拒绝删除有未提交改动的目录 worktrunk destroy task-slug [--force]create底层执行的是git worktree add .worktrunk/agent-id/task-slug -b agent/agent-id/task-slug basedestroy底层是git worktree remove .worktrunk/agent-id/task-slug git branch -D agent/agent-id/task-slug # 可选取决于是否需要保留分支为了安全destroy默认不删除含未提交改动的目录。如果你想保留 Agent 的中间产物做分析可以只删目录不删分支如果任务彻底完成分支也应该合并或删除。3.4 状态记录Agent 任务需要被审计在纯 Git 场景worktree 的状态无非是已创建/已删除。但 Agent 任务有更丰富的状态需求任务是否在运行、Agent 上一次活跃时间、当前所在分支与 base 分支的 commit 差异数量、日志文件路径等。Worktrunk 把状态记录在.worktrunk/state.json里同时每次任务活动都会更新 state 文件。这样worktrunk list可以输出类似下面的信息Agent IDTask Slug路径分支BaseCommit 差异数状态claude-code-1fix-login-redirect.worktrunk/claude-code-1/fix-login-redirectagent/claude-code-1/fix-login-redirectmain3 ahead, 0 behindactivecodex-2refactor-utils.worktrunk/codex-2/refactor-utilsagent/codex-2/refactor-utilsmain2 ahead, 0 behindidle状态文件还带了 last_command 字段记录最后一次执行的命令和退出码排查 Agent 意外中断时非常有用。4. 与 AI Agent 工具的配合如何让 Claude Code、Codex CLI 真正跑在 Worktrunk 里工具链的价值在于和 Agent 工作流的深度咬合。光有 Worktrunk 创建的隔离目录还不够你得把 Agent 会话正确引导进去。4.1 让 Agent 在指定目录启动会话最简单的方式是启动 Agent CLI 时指定工作目录。worktrunk switch fix-login-redirect cd .worktrunk/claude-code-1/fix-login-redirect claude # 或 codex但如果你的 Agent CLI 支持--directory或-C参数也可以一条命令直达cd $(worktrunk create --agent claude-code-1 --task fix-login-redirect --base main) claude --dangerously-skip-permissions注意--dangerously-skip-permissions会跳过 Agent 的权限确认这在并行场景里能减少大量人工干预但安全性也同步下降建议只在隔离的 worktree 里开启避免它乱动主工作区。4.2 Agent 会话中的 Git 操作引导Agent 在 worktree 里工作时它会自然地执行git命令但它不会理解你在一个 worktree 里这个特殊上下文。所以我在 Worktrunk 里内置了一个辅助命令worktrunk agent-hint这个命令会输出一段提示文本告诉 Agent 当前目录是一个隔离工作区、它的分支名是什么、base 分支是什么、应该把 commit 推到哪里。你可以把这段提示作为 System Prompt 的一部分传给 Agent。实际使用时我会在启动每条 Agent 任务的 Prompt 里加上一句你正在位于 .worktrunk/claude-code-1/fix-login-redirect 的隔离工作区中。 请在该目录内完成所有修改和提交。你要基于的分支是 agent/claude-code-1/fix-login-redirect 可随时 push 到 origin。不要触碰主目录中的其他文件。这样 Agent 即使没有显式理解 worktree 概念也能按照预期的隔离规则工作。4.3 并发限制如何控制 Agent 数量Worktrunk 层面不限制并发 Agent 数量但实际经验告诉我超过 5 个并行 Agent 后资源开销和冲突概率会急剧上升。我的建议是不要让两个 Agent 操作同一个任务目录同一个任务即使需要多个 Agent 协作也应该拆成子任务并分配不同的 worktree。在 CI/CD 场景Worktrunk 可以和 Github Actions 的 Job Matrix 结合使用每个作业用 Worktrunk 创建独立 worktree任务完成后自动销毁天然解决并行 Job 的代码冲突问题。5. 使用 Worktrunk 的避坑记录我在实际运行中踩过的五个坑这一部分是我最想分享的。Worktrunk 本身不复杂复杂的是现实环境的边界条件。下面这五个坑全部来自我实际使用过程中的血泪教训。5.1 大文件与依赖目录的重复开销每个 worktree 都是独立的目录拷贝如果你的仓库根目录下有大的node_modules/、vendor/或构建产物目录每创建一个 worktree 就等于多拷一份。10 个 Agent 就是 10 份 node_modules磁盘瞬间爆炸。解决方案有两条路一是用 symbolic link 把大目录统一指向一个缓存目录但要小心 Agent 同时改依赖引发冲突二是仓库层面使用 Git LFS 管理大文件worktree 之间共享 LFS 对象磁盘消耗能控制在合理范围。我推荐以第二种为主尤其是大二进制资源多的项目。5.2 断点续跑时 worktree 的旧状态问题Agent 任务中断后重新启动时Worktrunk 会恢复目录但这个目录可能残留上次运行产生的临时文件、缓存、日志等。这些残留物不是 Git 的一部分git status看不出来却可能干扰 Agent 的判断。我在 Worktrunk 里加了个worktrunk reset task-slug命令作用是先把当前 worktree 里该保留的配置备份然后把工作区恢复到 base 分支状态再重建目录。Agent 断线重跑时我一般会先 reset 一次确保环境干净。5.3 Windows 环境下的路径与符号链接坑Windows 上的 Git Worktree 有个特殊点路径中的正反斜杠和符号链接权限容易出问题。如果仓库里存在 symbolic link在 Windows 下创建 worktree 可能需要开启 developer mode否则 Git 无法创建链接文件Worktrunk 的create会直接报错。解决方式Windows 上优先用 Git Bash 运行 Worktrunk并在仓库根目录执行git config core.symlinks true。如果项目大量使用 symlink建议在 Linux 或 macOS 上跑 Agent 任务。5.4 Agent 的git push权限与上游分支设置Agent 在 worktree 里如果直接执行git push有时会因为没有设置 upstream 而失败。Git 2.37 默认的push.default是simple通常在推送同名分支时没问题但 agent 分支名带斜杠时偶尔会被误判。我的做法是让 Worktrunk 创建分支时直接设置上游git push -u origin agent/${agent_id}/${task_slug}或者至少在创建 worktree 时检查branch.autoSetupMerge配置确保 Agent push 时不会卡在上游分支缺失的问题上。5.5 无法轻易清空.worktrunk目录时的备份需求有时候 Agent 任务在 worktree 里产生了大量有价值的中间文件比如调试日志、临时实验脚本、性能分析报告。任务结束后直接destroy会把它们一起清掉而这个损失往往在几周后才发现。我给 Worktrunk 加了--archive参数销毁前先把目录打包成.tar.gz存到.worktrunk/archive/下。成本很低但救回过两次重要的分析结果。如果你也用 Worktrunk 跑有探索性质的任务建议默认开启这个参数。6. 为什么不用现成 worktree 管理工具Worktrunk 的边界与适用场景在动手写 Worktrunk 之前我调研过市面上一些 worktree 管理 CLI 插件如git-worktree-switch、git-worktree-manager等以及 IDE 自带的 Worktree 面板。结论是它们解决的是人类开发者管理多个 worktree的场景而 AI Agent 场景的多任务并发有完全不同的问题维度。6.1 直接使用 Git 原生命令的不足原生命令足够强大但缺少任务这个概念。它不会告诉你哪个 worktree 对应哪个 Agent、哪个任务处于什么状态、base 分支是什么。当你有 10 个 worktree 时git worktree list输出的路径、分支、分支看两眼还清楚但变成 10 个带agent/前缀的分支时人眼和脚本都不好处理。Worktrunk 的价值是给 worktree 加了一个任务上下文层让 Agent 相关状态一目了然并且可被脚本消费--json输出。这个能力对 CI/CD 和 Agent 编排系统很重要。6.2 何时不该用 Worktrunk必须实话实说并非所有场景都需要一个专门的工作流管理工具。如果你的团队只有两三个开发者每个任务一次性完成不涉及长期运行的 Agent 会话那么原生git worktree add完全够用。Worktrunk 引入的任务状态、Agent ID、生命周期管理反而显得多余。如果你的 Agent 工具本身支持 namespace 隔离比如 Codex CLI 的 sandbox 模式或者你只是单 Agent 顺序执行任务也大概率不需要 Worktrunk。它的最佳适用区间是多个 AI Agent 长期并行、任务粒度中等、需要隔离但不想管理复杂的 Git 命令。在这个区间里它带来的收益是最直观的。7. 下一步规划Worktrunk 如何继续演进工具做到能用的程度只是一个起点我目前对 Worktrunk 的规划集中在几个方向上。7.1 更深的 Agent Framework 集成现在的 Agent 接入方式基本靠目录隔离 Prompt 约束这套是通用的但没有深入到 Agent Framework 的框架层。未来我打算为 Worktrunk 提供一个小型 SDK让 Agent 在 Python/TypeScript 中可以直接调用Worktrunk.create_task()创建 worktree在执行 Actions 时自动使用当前任务的 worktree 上下文。这样能力边界会更清晰Agent 框架也能感知任务状态。7.2 更可靠的任务依赖与合并流程现在destroy只是简单删除 worktree 和可选分支但真实项目里任务与任务之间往往有依赖任务 B 可能依赖任务 A 的代码所以 B 的 base 分支并非 main而是 A 的分支。Worktrunk 目前对多级 base 分支支持有限我计划把依赖树纳入状态机让destroy能自动处理分支合并顺序。7.3 观测与审计能力的加强AI Agent 开发最容易被忽视的是审计。Agent 改了哪些代码、这些改动有没有经过 review、合并到主分支时有没有引入意外变动。Worktrunk 计划增加一个worktrunk report task-slug命令输出该任务完整的 commit 列表、改动文件清单、测试结果摘要方便 review 阶段直接消费。这对团队协作的价值会超过对个人开发者的价值。写在最后工具是服务于习惯的Worktrunk 到现在没有做得很复杂所有命令加起来也能在两分钟内学会。它的核心贡献是让并行 AI Agent 工作流从一个需要时刻警惕目录冲突的游击队模式变成一个环境隔离、状态可查、清理干脆的正规军模式。我个人在实际操作中的最大体会是并行开发的两难不在并行本身而在并行后的隔离与聚合。Worktrunk 帮我解决了一部分尤其是任务级隔离这块聚合和 review 这块我还在靠 Git merge 和人工 review 撑着。如果你也在用多个 AI Agent 并行写代码现阶段最值得采纳的或许不是某个工具而是一个思路——每个 Agent 都应该有自己独立的工作区、明确的基线分支、以及一个可安全销毁的环境。Worktrunk 会把这件事变得顺手很多。