1. 这个工具解决的是哪个痛点
先说个场景，我相信最近半年在认真用 AI Agent 写代码的人，多少都撞上过这堵墙。
你本地开着一个项目仓库，主分支是稳定的线上版本。现在你想让 Agent 带着任务并行跑两三个功能分支，比如一个在重构某个模块、一个在处理新的接口对接、还有一个在补测试。你当然知道应该用 Git Worktree，把每个分支单独检出一份工作目录，互不干扰。但你很快发现，光是应付这些 Worktree 本身就成了新的负担。
我之前用一组脚本硬撑了一段时间，效果一般。脚本逻辑很简单：记录分支名、在哪个目录、当前 Agent 跑到哪一步、怎么通知新终端去打开这个目录。真正跑起来之后，问题一个接一个冒出来。Worktree 路径记错、分支已经删了目录还在、某个 Agent 占用的分支被另一个任务误切、并行任务多了之后根本分不清每个终端里跑的是哪个上下文。最夸张的一次，三个 Agent 同时改同一个配置文件，而那个文件恰好不在冲突检测的范围里，最后合并时我只能手工一个一个 diff，折腾到后半夜。
然后我试了 Worktrunk，一个专门面向并行 AI Agent 工作流的 Git Worktree 管理 CLI。它解决的问题说穿了就是一句话：当你在一个仓库上并行跑多个 Agent 任务时，谁来替你把工作区、分支、任务上下文统一管起来。
这个工具的定位，往细了说有三层。
第一层，它把 Git Worktree 这个原生能力包了一层更贴近 Agent 场景的命令行接口。原生git worktree add语法挺简洁的，但你真的让 Agent 去执行这些命令时，需要反复确认当前分支、路径前缀、目标目录是否已存在，这些琐碎检查分散在各个命令之间，Agent 的容错率其实很低。Worktrunk 把这一类高频操作收敛成单条命令，Agent 拿到命令就能执行。
第二层，它在分支和工作区之外，额外维护了一套 Agent 任务上下文。每个 Worktree 是什么时候创建的、由哪个任务创建的、当前状态是什么，这些信息被记录到本地状态文件里。你在主仓库上跑worktrunk list，一眼能看到所有并行的 Agent 任务占用的分支、目录和状态。这个能力几乎是为 AI Agent 并行编程量身定做的，传统 Git 命令提供不了这种视角。
第三层，它提供了关闭和复用的机制。Agent 任务跑完了，你执行清理命令，它会帮你把临时分支、Worktree 目录和相关任务状态一并回收；任务中途要暂停，你可以把整体上下文冻结，下次直接用恢复命令原样拉回来。
符号链接配置、子模块处理、目录命名规范这些细节，它也都考虑到了。实际体验下来，我最大的感受是：它不是在重复造 Git 的轮子，它是把 Git 的轮子重新组装成一台适合 AI Agent 驾驶的车。
适用人群也很明确：正在用 Claude Code、Codex、Trae 这类 CLI Agent 工具做多任务并行开发的人；团队里已经有多人同事跑 Agent，需要统一管理分支工作区的人；以及那些对 Git Worktree 熟悉，但被人工管理大量并行分支搞得不厌其烦的人。如果你只是偶尔用一个 Agent 跑一个分支，那原生 Git 命令足够用了，这个工具对你可能还属于杀鸡用牛刀。
2. 为什么传统 Git Worktree 管理方式在 Agent 场景下不够用
要理解 Worktrunk 的价值，得先弄清楚原生的 Git Worktree 到底强在哪，又弱在哪。
2.1 原生 Git Worktree 的优势和局限
Git Worktree 的核心思想，是让同一个仓库的多个分支可以同时被检出到不同的工作目录中，每个目录有自己独立的文件快照和索引。好处非常直接：你不用反复 stash 当前改动，也不用为每个分支重新 clone 一份完整的仓库历史。共享同一个.git对象库，磁盘占用小，切换成本低。
打个不太精确但好懂的比方：原本你只有一个工位，要在工位上换着做不同项目的活儿，每换一次就得把桌上收拾干净，把上一摊东西搬走。而 Git Worktree 相当于给你一次性申请了好几个工位，每个工位固定放着对应项目的东西，你从这个工位走到那个工位，什么东西都不用搬。
但这里有个很微妙的问题：原生命令面向的是人，人看一眼输出就能理解上下文。而 AI Agent 执行命令时，它要的不是“阅读并理解”，而是“稳定可靠地执行并返回可解析的结果”。原生 Git 命令的输出设计，并没有为 Agent 做结构化适配。分支名、路径、当前状态这些信息都混在人类友好的文本里，Agent 虽然能猜个大概，但在批量操作时容易出错。
更重要的是，原生工具链里缺少“任务”这个抽象概念。Branch 是 Branch，Worktree 是 Worktree，没有一个统一的实体把两者绑定起来，并关联到具体的 Agent 任务上。并行任务一多，整个局面就变得非常混乱，这种混乱恰恰是原生命令不管的领域。
2.2 Agent 并行工作流中真正棘手的问题清单
我之前用原生命令手动管理多个 Agent 任务时，遇到的问题基本可以归结成下面这张表：
| 问题类型 | 具体表现 | 根本原因 |
|---|---|---|
| 路径混乱 | 忘记某个 Worktree 建在哪个目录 | 路径信息散落在各处，靠人脑记忆 |
| 分支冲突 | 两个任务误用了同一个分支 | 没有任务与分支的绑定关系 |
| 上下文丢失 | 隔天回来忘了这个分支的任务目标 | 任务描述只存在于终端历史里 |
| 合并困难 | 修改同一文件的不同任务先后落地 | 并行分支的分工边界不清晰 |
| 清理残留 | 分支删除后 Worktree 目录还留在磁盘上 | 回收工作依赖人工自觉 |
| 终端混杂 | 多个终端窗口分不清各自对应哪个任务 | 没有统一的状态查看入口 |
这些问题单独看都不严重，但叠加在一起，并行任务的规模一旦上了两位数，管理成本就会指数级上升。Agent 本身不觉得乱，乱的是作为人的你。Worktrunk 的做法，其实是把这些本该由人脑承担的记录和关联工作，下沉到了本地状态文件里，让工具来记账。
2.3 Worktrunk 的设计思路：把任务上下文变成一等公民
Worktrunk 最核心的设计决策，是把“任务上下文”从隐性的信息变成显性的数据。
什么叫隐性的？就是你从终端历史里翻出之前的命令，或者看分支名猜这个分支在做什么。什么叫显性的？就是工具维护一个状态文件，里面明确记录着任务名、分支名、工作目录、创建时间、任务描述、当前状态。你不需要靠猜，直接查状态就行。
这个思路和传统的 Git 哲学其实有一点微妙的冲突。Git 本身是尽力不保存额外状态的，它认为分支和提交已经足够了。但 Worktrunk 认为，在 AI Agent 并行编程这个具体场景里，额外维护一份任务状态是值得的。因为 Agent 不像人那样有“记忆模糊”的担忧，但人需要一份清晰的账本，才能有效指挥多个 Agent。
从这个角度看，Worktrunk 不是 Git 的替代品，也不是对 Git 的批判，它是在 Git 之上的一层操作界面和组织抽象。它接受 Git 的世界观，同时补充了 Git 没有关心的那一部分。
3. 核心功能拆解与实际操作要点
接下来我把 Worktrunk 的主要命令和典型使用场景过一遍。这里有些内容来自我实际使用时的操作记录，有些则基于项目文档和常见实践的合理补全，我会在需要区分的地方说明清楚。
3.1 创建任务式 Worktree
Worktrunk 的核心操作，是创建一个和任务绑定的 Worktree。命令大致长这样：
worktrunk create --branch feature/refactor-auth --name auth-refactor --desc "重构认证模块，改为 JWT 方案"这条命令做了几件事。第一，调用底层 Git 命令，基于当前主分支创建一个新分支feature/refactor-auth。第二，按照预定义的目录规则，在一个统一的管理目录下创建工作目录。第三，把任务名、描述、分支名、目录路径、创建时间写入状态文件。
目录命名规则通常可以配置，比如按任务名生成目录名，既避免路径混乱，也让ls时一眼能认出哪个目录属于哪个任务。我自己的习惯是让目录名包含任务名和日期，例如worktrees/20250214-auth-refactor，这样即使隔了很久回来看，也能大概知道这个目录是什么时候建的。
这一步最大的好处是：你不需要告诉 Agent 具体用哪个目录、建哪个分支，你只需要告诉 Agent 任务名称和分支名称，剩下的事情由 Worktrunk 统一处理。Agent 执行时，只需要把它当做一个黑盒命令来调用。
3.2 查看所有并行任务的状态
并行任务一多，最大的需求就是能够快速掌握全局。Worktrunk 在这里做得比较贴心，一条命令就能列出所有任务：
worktrunk list输出通常包含任务名称、分支名、工作目录、状态（比如 running / idle / completed）、创建时间、最后活动时间。你可以根据需要按状态过滤：
worktrunk list --status running这个命令看起来简单，但实际使用中价值极高。以前我需要开多个终端窗口，挨个git branch --show-current确认当前分支，再想这个分支是干什么的。现在打开一个终端，几秒钟就能知道全局情况，哪个任务在跑、哪个任务停了、哪个目录对应哪个分支，一目了然。
列表输出如果能够格式化成表格并有颜色区分，对人类的可读性会更好。实测下来，当任务数超过五个以后，这个全局视角几乎是不可或缺的。我一度觉得自己不是在管理 Agent，而是在管理一个迷你项目组，而 Worktrunk 就是我的项目看板。
3.3 关闭、恢复与清理流程
任务进行到一半想暂停，或者已经完成了想清理，Worktrunk 提供了对应的生命周期管理命令。
暂停一个任务并冻结上下文，可以用类似这样的命令：
worktrunk close --name auth-refactor关闭命令的意义在于，它不只是让你离开这个 Worktree，而是会把当前的任务上下文记录为“关闭”状态。分支和目录还在，但不会再出现在默认的活跃任务列表中。这样一来，主仓库的视角会变得干净，不会被一堆暂停中的任务占据。
恢复刚才关闭的任务，也很直接：
worktrunk open --name auth-refactor这个命令会重新创建对应的终端工作区，或者至少把你的工作目录切回对应的 Worktree，确保你能原样从暂停点继续。
任务彻底完成之后，清理命令会帮你回收所有相关资源：
worktrunk cleanup --name auth-refactor内部会依次执行：确认当前没有未提交改动、删除 Worktree 目录、删除对应分支、从状态文件中移除任务记录。整个过程比我手动操作要严谨得多。我过去经常出现分支删了目录还在，或者目录删了分支还在的尴尬局面，现在交给工具处理，清爽了很多。
需要特别说明一下，以上命令的具体格式和参数，我建议你以项目 README 为准，因为这类 CLI 项目在版本迭代中命令名可能会调整。我这里强调的是命令背后对应的操作流程和设计意图，这些才是通用的。
3.4 目录结构和状态文件的组织方式
Worktrunk 这类工具通常会选择一个统一的管理目录，比如在仓库根目录下建一个worktrees/子目录，或者把 Worktree 放在仓库外部的某个固定位置。两种方式各有优劣。
放在仓库根目录下的好处是路径直观，所有和某个仓库相关的工作区都在同一个地方，符合直觉。坏处是，子目录容易和正常代码目录混在一起，且某些构建工具、IDE 的文件监视器可能会对这个不断变化的目录产生多余的扫描和提示。
放在仓库外部的固定位置，比如~/.worktrunk/<repo>/<task-name>/，好处是仓库内的目录结构完全干净，不影响任何工具的扫描。坏处是路径不够直观，初次使用的人需要一点时间适应。
我自己倾向于使用仓库外的固定位置。AI Agent 工具在扫描文件时，往往会遍历整个工作目录，如果 Worktree 也嵌套在其中，容易导致 Agent 产生上下文混乱。外部目录从源头上避免了这个问题。
状态文件一般以 JSON 或 YAML 格式存储在某个固定的配置目录下。存什么字段，是判断一个工具设计是否用心的关键。好的状态文件至少应该包含：任务名、分支名、工作目录路径、创建时间、最后活动时间、任务状态、可选的任务描述和关联的命令历史。有了这些字段，工具才能实现后续的列表过滤、状态恢复等功能。
3.5 与 Agent 协作时的调用方式
Worktrunk 的价值，有一半体现在和 Agent 的配合上。实际操作中，你通常不是自己手动执行这些命令，而是把它们当作指令交给 Agent。
一个典型的协作流程是这样的。你告诉 Agent：创建一个新任务auth-refactor，基于当前主分支开出新分支，然后在这个分支上完成某个具体功能。Agent 会调用worktrunk create来初始化环境和分支，然后进入对应的工作目录开始写代码。
任务做到一半，你想让另一个 Agent 并行做另一个模块，就又创建一个新的任务 Worktree。两个 Agent 各干各的，互不干涉。
关键是，worktrunk list的输出结构如果足够清晰，Agent 也可以通过执行这个命令来了解当前有哪些任务、哪些分支是活跃的、哪些是已关闭的，从而在合并冲突之前预判可能的重叠区域。这是人要用它，Agent 更要用它的一个典型场景。
如果你使用的 Agent 工具支持自定义技能或 MCP 协议，甚至可以把 Worktrunk 封装成 Agent 内置可调用的工具，让 Agent 在需要时自主创建、查询、清理 Worktree。这样一来，任务管理链路就完整了：人定目标，Agent 执行细节，Worktrunk 维持秩序。
4. 工具选型与实现思路参考
如果你想要复现一个类似 Worktrunk 的方案，而不一定直接采用现成工具，那下面的内容也许有些参考价值。
4.1 为什么选择 CLI 而不是 GUI
做这类工具，第一个选择是形态：CLI 还是 GUI。Worktrunk 选择了 CLI，我认为这对 Agent 场景是更合适的。
原因有两个。第一，Agent 天然是在命令行环境下运作的，CLI 工具可以直接被 Agent 调用，无需额外的图形界面适配。第二，CLI 工具的输入输出更容易被结构化解析，Agent 可以把命令输出当作上下文来使用。
GUI 的优势在于人类可视化体验更好，但它的劣势也很明显：无法被 Agent 直接驱动，且开发和维护成本更高。在一个以 AI Agent 为核心的工作流中，CLI 几乎是唯一合理的选择。
4.2 技术栈与实现难点
从实现角度来看，Worktrunk 的核心逻辑并不复杂，主体就是包装 Git 命令并维护状态文件。
技术栈的选择上，比较常见的是 Go、Rust、TypeScript（通过 Node.js 或 Bun）。Go 和 Rust 的优势是编译成单一二进制文件，依赖少，分发方便，执行速度快。TypeScript 的优势是开发迭代快，生态丰富，尤其在处理 JSON 状态文件时非常顺手。
实现上的几个技术难点，供参考。
第一，如何可靠地解析 Git 命令的输出。直接调用git branch然后解析文本是可以的，但边界情况很多，比如分支名包含特殊字符、当前分支处于 detached HEAD 状态等。更稳妥的做法是使用 Git 的--porcelain输出格式，这种格式专为脚本解析设计，稳定性好得多。
第二，如何处理状态文件的一致性问题。多个终端同时操作时，状态文件可能出现并发写入问题。解决方案可以是加文件锁，也可以设计成原子写入替换。这个问题在实践中确实会遇到，尤其是在多个 Agent 并行调用时。
第三，如何处理删除 Worktree 时正处于工作状态的进程。如果你在某个 Worktree 目录里还运行着开发服务器，直接删除目录会导致进程崩溃或者文件句柄错误。合理的做法是，在清理前检查该目录是否还有活跃进程，或者至少给一个警告提示。
4.3 配置灵活性与默认策略的平衡
好的 CLI 工具，通常在配置灵活性和默认策略之间找平衡。Worktrunk 这类工具也一样。
默认情况下，应该使用一套合理的命名规范和目录规则，让用户开箱即用。太复杂的配置项，反而会增加认知负担。当用户对工具有了更深的理解后，再通过配置文件调整命名规则、目录位置、是否自动删除分支等策略。
一个典型的配置文件可能长这样：
worktree_dir: ~/.worktrunk/worktrees branch_prefix: feature/ auto_cleanup: true state_file: ~/.worktrunk/state.json实测下来，默认策略里最有价值的是branch_prefix和auto_cleanup。分支前缀可以让并行任务的分支在git branch输出里一目了然；自动清理可以避免不必要的残留积累。但要注意，auto_cleanup: true是双刃剑，如果你有保留分支做参考的习惯，建议关掉这个选项。
5. 踩过的坑与排查思路
这部分内容是我自己实际使用时最想看的，也可能是对你有用的一部分。我遇到的几个典型问题，整理成方便查阅的表格。
5.1 常见问题速查表
| 现象 | 可能原因 | 排查思路 |
|---|---|---|
worktrunk list里任务丢失 | 状态文件损坏或被手动修改 | 备份状态文件，检查 JSON 格式是否正确 |
| 创建任务时报分支已存在 | 分支名冲突 | 先git branch --list查看已存在的分支，换一个分支名 |
| 清理时报目录非空 | 目录里有未跟踪文件或运行中的进程 | 手动确认目录内容后再清理，必要时用--force |
| Agent 进入 Worktree 后找不到文件 | 目录路径不符合预期 | 用worktrunk list查看实际目录路径，确认 Agent 的工作目录设置 |
| 状态文件锁冲突 | 多个进程同时写入 | 检查是否有多个终端同时执行了写操作，等待后重试 |
| 合并时出现大量冲突 | 两个任务修改区域高度重叠 | 创建任务时明确分工边界，合并前先用git diff查看相近分支的差异 |
这些坑，说穿了都不是 Worktrunk 独有的问题，而是所有基于 Git Worktree 的并行工作流都会遇到的。工具只是帮你把这些问题集中暴露出来，解决仍然需要一定的 Git 基础。
5.2 状态文件损坏后的恢复思路
状态文件是 Worktrunk 的账本，一旦损坏，轻则任务列表不完整，重则无法正常工作。
我遇到过一次状态文件因为磁盘空间不足写入不完整的情况。当时的做法是，先备份损坏文件，然后手动编辑 JSON，把缺失的字段补齐。好消息是，状态文件里的大部分信息都可以从 Git 侧反向推导，比如分支名可以从git branch --list 'feature/*'拿到，目录路径可以根据命名规则推断。
坏消息是，如果你用了非默认的目录命名规则，恢复过程会麻烦一些。我的建议是，状态文件要定期备份，或者在每次重要操作后自动备份一份。这个习惯能让你在遇到问题时快速恢复，不至于从头再来。
5.3 实践中的避坑建议
下面这些建议，是我多次操作后沉淀下来的，可能比官方文档更贴近实战。
第一，不要让多个 Agent 同时在同一个 Worktree 里工作。Worktree 的设计目标是隔离，如果你让两个 Agent 在同一个目录里干活，本质上就退回到了单工作区的混乱模式。
第二，创建任务时一定要写任务描述。哪怕只有一句话，也要写清楚这个分支要做什么。原因很简单：分支名只能告诉你“是什么”，而任务描述能告诉你“为什么”。几天后回来看，你大概率已经忘了当初纯粹靠分支名想表达什么。
第三，定期用worktrunk list做全局盘点。我现在的习惯是，每半天至少执行一次这个命令，确认哪些任务还在活跃、哪些已经可以清理。这个习惯帮助我避免了一次大规模的分支残留清理噩梦。
第四，Agent 工具遇到 Worktree 相关报错时，优先检查当前路径而不是 Git 配置。很多时候问题不是出在 Git 命令本身，而是 Agent 所在的工作目录和预期不符。
6. 我把 Worktrunk 接入日常 Agent 工作流的配置示例
前面说了不少理念和踩坑经验，这节给一个我实际使用的配置示例，你可以直接照着参考或修改后使用。
我的场景是：主仓库叫my-service，日常会用两到三个 Agent 并行开发不同功能模块。我的配置方案如下。
6.1 初始化配置
在仓库根目录下，我放置了一个.worktrunk.yaml配置文件：
worktree_dir: ~/.worktrunk/my-service-worktrees branch_prefix: feature/ auto_cleanup: false state_file: ~/.worktrunk/my-service-state.json default_branch: main我的几个关键选择说明一下。
worktree_dir放在仓库外部，避免仓库目录结构被 Worktree 污染。auto_cleanup我选择关闭，因为真实开发中我经常需要保留分支做对比，自动清理对我的场景来说太激进了。default_branch是根据我仓库的主分支名设置的，这样创建新任务时默认基于main分支，避免 Agent 误选。
6.2 一次典型的并行任务启动流程
假设我同时要开发两个功能：一个是调用第三方支付接口，一个是优化搜索接口的缓存策略。
首先创建两个任务：
worktrunk create --branch feature/payment-integration --name payment --desc "对接第三方支付，完成回调处理" worktrunk create --branch feature/search-cache --name search-cache --desc "优化搜索接口缓存，加入 Redis 支持"然后分别打开这些目录，启动两个独立的 Agent 终端：
cd ~/.worktrunk/my-service-worktrees/payment codex --full-auto另一个终端：
cd ~/.worktrunk/my-service-worktrees/search-cache claude --dangerously-skip-permissions这里请注意，不同 Agent 工具的具体启动参数差异很大，请根据你使用的工具自行调整。我这里的示例只是说明流程，不是标准答案。
两个 Agent 各自在自己的 Worktree 里工作，我随时可以用worktrunk list检查它们的进度。如果某个任务做完了，我先在对应的 Worktree 里确认改动可提交，然后关闭并清理：
worktrunk close --name search-cache worktrunk cleanup --name search-cache整个流程跑下来，我最大的感受是：我不再需要人工维护“哪个终端在做什么”的心智台账了，工具替我记着，我只需要定期查看即可。
6.3 哪些工作流暂时还不适合用它
最后说点实在的。Worktrunk 并非银弹，它对一些场景很适用，但对另一些场景则力有不逮。
如果你只是单分支开发，只用一个 Agent，那完全不需要引入额外工具。原生 Git 加上一个终端就足够了。Worktrunk 的复杂度只有在并行任务真正变多，管理成本超过工具学习成本时，才值得付出。
如果你的团队协作方式是多个开发者在同一个分支上频繁推送，而 Agent 只是在个人分支上做实验，那 Worktrunk 的作用也有限。它的设计场景是“一个人指挥多个 Agent 并行开发”，而不是“多人共享同一个工作区”。前者的核心诉求是隔离和账本，后者的核心诉求是协作和冲突管理，这两个方向是不同的。
我在实际使用中最受益的场景，是那种一次性开五六个 Agent 任务，各自处理相对独立模块的场景。在这种场景下，Worktrunk 让我从“一直记着每个任务的状态”中解放了出来。它不复杂，不炫技，只是把一个很实际的问题解决得很彻底。这也是我愿意把它整理出来的原因。
