1. 为什么我给每个 AI Agent 单独开了一个工作区先讲一个真实的场景。上个月我同时推进三件事用 codex CLI 改一个接口的鉴权逻辑用 Claude Code 调前端页面的样式问题还给另一个 Agent 派了修测试失败的任务。三个 LLM 驱动的 Agent 同时开工听起来很高效结果十分钟后我就后悔了——因为它们共用同一个工作目录。当三个 Agent 往同一个git status里写文件时场面完全失控。Agent A 刚把auth.go改完还没提交Agent B 又基于旧代码改了一遍同一个文件Agent C 执行测试时跑出来的报错根本分不清是哪个改动引入的。我原本的计划是并行提速实际变成了协作互踩。那天的最终结局是我把全部改动 stash 掉一个一个 Agent 单独串行跑完——等于回到了最原始的工作模式。这不是单个 Agent 的问题而是工作环境的问题。任何一个智能体本质上都是读取当前目录状态、修改文件、执行命令的循环。如果目录里混着多个不相关的任务再聪明的 Agent 也没法判断哪些改动属于自己。所以正确的思路是每个并行任务必须有独立的、物理隔离的工作目录。Git Worktree 是解决这个问题的原生机制但它只提供了最底层的多工作区能力离面向 Agent 的多任务管理还差一层。这就是我做 Worktrunk 的原因——一个专门为并行 AI Agent 工作流设计的 Git Worktree 管理 CLI。它做的事情很简单把创建一个独立工作区、绑定到一个任务、记录 Agent 上下文、用完后安全回收这一整套流程变成几个固定的命令。这篇文章我会从头讲清楚三件事Git Worktree 本身的原理和限制、Worktrunk 到底在你和原始 git 命令之间加了什么、以及在真实项目里让多个 Agent 并行跑任务的完整操作流程。适合正在用或者准备用 codex CLI、Claude Code 这类 AI 编程工具的开发者也适合需要管理大量并行分支的团队。2. Git Worktree 的原生能力与它的局限性2.1 一套 .git 元数据多个独立工作区先花点时间把 Git Worktree 的原理说透。普通 Git 仓库的结构是一个.git目录加一套工作区文件你git checkout main切到 main 分支工作区文件就变成 main 分支对应的内容。如果你不想切分支但又想同时在另一个分支上干活传统做法是再 clone 一份仓库——这会导致.git对象数据库也复制一份占用双倍磁盘空间。git worktree add解决的正是这个问题它允许同一个仓库拥有多个工作目录但这些目录共享同一个.git对象数据库和引用refs。执行这条命令后Git 会在.git/worktrees下生成一个只包含该工作区元数据的小目录里面记录了指向主.git的链接、当前 HEAD、index 等。你可以把它理解成一份乐高积木图纸多套正在搭建的成品——图纸只有一份但每套成品都是独立的。我举个例子git worktree add ../wt-feature-login -b feature/login这条命令会创建../wt-feature-login目录并基于当前分支新建feature/login分支。在这个目录里你可以随意修改文件、提交、切分支完全不影响主工作区和其他 worktree。列出所有工作区git worktree list输出大概是这样的/path/to/main-repo main abc1234 [main] /path/to/wt-feature-login feature/login def5678 [feature/login]清理一个已经合并完成的工作区先在工作区里确认无未提交改动然后执行git worktree remove ../wt-feature-login如果工作区里有未提交的改动Git 会拒绝删除并提示你使用--force。这个保护机制在大部分情况下是好事但对于我们跑 Agent 的场景来说反而成了一个需要额外处理的环节——因为 Agent 跑完任务后经常会留下各种临时文件、未提交的修改、甚至测试产物你没法指望它自己整理干净。2.2 同一分支冲突Git 的只允许一个人坐同一个座位Worktree 有一个设计上的硬限制同一个分支在同一时间只能被一个工作区 checkout。你如果试图在主工作区和旁边的 worktree 里同时 checkout mainGit 会直接报错fatal: main is already checked out at /path/to/wt-feature-login这个限制的出发点是防止两个工作区同时修改同一分支导致引用错乱——Git 内部对分支的修改是全局的如果两个工作区各自推进同一个分支reflog 和引用更新就会产生竞争。对于人类开发者来说这个限制很合理你在 main 上做热修复另一个 worktree 也 checkout main两个人同时提交到底谁代表最新状态说不清楚。但对于 AI Agent 工作流这个限制意味着你必须做好分支规划每个 Agent 的工作区都应该基于基分支创建一个专属 feature 分支而不是在基分支上直接工作。Worktrunk 在创建工作区时会默认执行-b feature/xxx的创建流程避免 Agent 不小心撞进这种限制里。2.3 原生 Git Worktree 解决不了的问题刨去原理Git Worktree 本身有两个明显的短板第一它只提供了命令原语没有任何任务管理的概念。你创建了十个 worktree每个对应什么任务、是给哪个 Agent 跑的、已经跑了多久、最近一次提交是什么时候这些东西 git 完全不知道需要你自己在一个外部表格或文档里记。第二它没有一个干净的回收流程。Agent 跑完任务后工作区里往往残留大量文件你先要处理未提交的改动然后确认分支是否已合并最后才能 remove。这个流程手动做一两次没问题做十次就想骂人了。另外还有一层体验上的问题AI 编程 CLI比如 codex CLI、claude 系列在工作时并不知道自己在哪个 worktree 里也不会主动告诉你我现在是基于 feature-x 分支工作。如果你不在一开始就规划清楚Agent 很容易在工作区里搞出混乱的提交记录。所以我在设计 Worktrunk 时把任务上下文、Agent 绑定、状态追踪、自动回收这些原本散落在命令行之外的事情全部收进了配置文件和一组命令里。3. Worktrunk 的核心设计Agent 生命周期而不是 human 习惯3.1 先定义配置再用命令操作 workspaceWorktrunk 的设计思路和大多数 Git 扩展不一样它没有把你当成一个偶尔切分支的老手而是把你的工作流定义成一个接一个的任务每个任务对应一个独立工作区。所以在 Worktrunk 里核心概念叫workspace含义是一个给某个 Agent或你自己跑特定任务用的 Git Worktree。安装完 Worktrunk 后README 里有针对 macOS / Linux / Windows 的安装方式实际上是一个单二进制解压后放到 PATH 里就行第一步是初始化worktrunk init这条命令会在你的仓库根目录生成一个.worktrunk.toml配置文件。初始配置大概长这样[project] name my-service default_base_branch main agent_registry [codex, claude, zcode] [policy] max_workspaces 8 disk_quota_per_workspace 8G prune_after_days 7这里我解释一下几个关键字段。agent_registry是允许绑定的 Agent 类型列表——我目前常用 codex CLI 和 Claude Code所以注册这两个就够了。max_workspaces是并行工作区数量上限防止哪次批量任务创建把整块磁盘吃满。disk_quota_per_workspace是软配额实际工作区大小超过这个值worktrunk status会警告但不阻止操作。prune_after_days是自动回收的宽松期限超过 N 天还没合并的 feature 分支会在 status 里被标记为 stale。3.2 创建一个绑定任务的 workspace新建任务工作区worktrunk add --task feature/user-profile-optimization --agent codex --base main这条命令背后实际执行的动作是根据任务名生成一个规范化的工作区目录名约定是wt-{task-key}如果名字冲突就自动追加短 hash。执行git fetch origin拉取最新远端引用。基于origin/main创建新分支feature/user-profile-optimization。用git worktree add创建实际目录。在.worktrunk/state.json里写入工作区元数据创建时间、关联 Agent、任务描述、当前分支、最近提交时间。整个过程中最有价值的产物其实是最后那一条元数据。它让所有工作区可查询、可追踪、可回收。你随时可以运行worktrunk list输出一个表格WORKSPACE BRANCH AGENT STATUS UPDATED wt-feature-login feature/user-login codex active 2m ago wt-fix-test-flaky fix/test-flaky claude pending 1h ago wt-feature-report feature/export-report codex merged 3d agoSTATUS一列是核心active表示最近两小时内有提交或文件变更pending表示创建了但 Agent 还没真正产出merged表示分支已经合并回主分支stale表示超过 prune 天数没有活动。3.3 回收一个 workspace比删除目录多做了两步单个任务跑完后干净地回收worktrunk rm wt-feature-login这个命令会依次检查分支是否已经合并到 base 分支如果没合并会提示你确认是否需要保留分支然后执行git worktree remove --force因为 Agent 大概率会留下未提交文件最后把配置文件和 state.json 里的记录一并清掉。很多人不理解这一步为什么不直接git worktree remove。区别在于当你有十个工作区时你根本记不住每个分支的状态而 Worktrunk 把要不要保留分支的判断集中到了同一份状态文件里。你还可以用一个命令批量清理所有merged状态的工作区worktrunk prune加上--merged-only参数之后非常安全它会在确认分支合并后才执行删除清完的空间相当可观。4. 并行 Agent 场景下的配置实战4.1 单 Agent 绑定把一个 codex CLI 任务跑进独立工作区最常见的用法是给 codex CLI 开一块专属工作区。流程就是三步worktrunk add --task fix-auth-token-refresh --agent codex --base main cd wt-fix-auth-token-refresh codexcodex CLI 进入目录后会读取当前仓库状态自然就知道自己在哪个分支上。这里有个细节值得注意Worktrunk 在创建工作区时会自动在目录下生成一个AGENTS.md如果项目原本没有的话内容是把 workspace 的任务描述、所属 Agent、基分支信息写进去# Task Context - Task: fix-auth-token-refresh - Base branch: main - Current branch: fix/fix-auth-token-refresh - Workspace created by: Worktrunk - Agent: codex像 codex CLI、Claude Code 这些工具都有读取AGENTS.md的能力它们会根据这些约束来理解自己的任务边界。这个文件的本质作用是把你在干什么变成 Agent 可直接读取的上下文信息。之前我用裸 worktree 的时候每次都得在对话里重新交代一遍背景有了这个文件之后Agent 一进场就知道自己该做什么。4.2 多 Agent 并行三四个工具互不干扰的关键配置同时跑多个 Agent 时最核心的约束是分支隔离。Worktrunk 每次add都会为任务创建独立分支但如果你没有指定--base它默认使用配置里的default_base_branch。我的一个建议是不要让多个工作区在同一时间修改同一批文件。即使工作区物理隔离如果两个 Agent 的任务都落在src/pkg/user/这一小块区域合并回主分支的时候仍然会有大量冲突。我实际跑的并行配置是三个工作区worktrunk add --task feature/strip-logging --agent codex --base main worktrunk add --task fix/undefined-null-issue --agent claude --base main worktrunk add --task chore/deps-update --agent zcode --base mainzcode是我偶尔会用的另一个 CLI 工具这里不展开只是说明 Worktrunk 的 Agent 注册机制允许你把任意命令行产物映射成规范化名称。这三个工作区的目录彼此独立git status互不影响构建缓存也完全隔离。唯一的代价是磁盘空间——每个工作区都是一份完整的 checkoutNode.js 项目还得各自装一遍node_modules。4.3 磁盘空间评估什么情况下该设配额说到磁盘就得算一笔账。普通仓库不带依赖的轻量 checkout 大约几十到几百 MB但如果项目里有node_modules或者vendor目录每个工作区的大小直接翻倍。我之前测过一个小型 Monorepo主目录 三个带依赖的工作区总共占了 6.4GB其中 80% 以上都是重复安装的依赖。所以在创建大量并行工作区之前建议先看一眼.worktrunk.toml的配额配置。Worktrunk 不会替你阻止依赖安装但它会在工作区超出配额时在worktrunk list里打上警示标记并且可以在prune时优先建议回收体积最大的工作区。这个机制是个提示器不是砍刀——真正的判断还是得你来定。4.4 状态检查和人工介入Agent 自己跑任务但人工要盯状态。我用得最多的两个配合是worktrunk status这个命令和worktrunk list略有区别status会更详细地列出每个工作区是否有未提交改动、最近一次 commit 的作者和时间、以及当前 HEAD 落后或领先 base 分支多少提交。格式类似wt-feature-login (feature/user-login) - clean: 3 committed changes - head: 1 commit ahead, 0 behind origin/main - last activity: 12 minutes ago - size: 4.2GB (hydrated)如果你有一个长时间跑的任务想跟进worktrunk watch wt-feature-login会每 30 秒刷一次状态直到你按 CtrlC。这个命令在盯 codex CLI 跑长任务时特别实用不需要频繁切终端窗口。5. 我踩过的坑同一分支冲突、软链失效、磁盘爆满5.1 坑一Worktree 在同一分支上直接罢工第一次用 Worktrunk 时我踩了个直觉坑。我创建好工作区之后习惯性在wt-xxx目录里执行git pull结果报错error: Pulling is not possible because you have unmerged files.这是我让 Agent 直接基于 main 分支改动留下的后遗症。严格来说更常见的坑其实是创建 worktree 时忘了指定-b然后在两个目录里都切到了 main第二个目录里一执行命令就会报出 already checked out at ... 的错误。Worktrunk 创建的 workspace 默认都会新建分支所以基本绕开了这个坑但当你手动执行git worktree add时就容易犯。我的经验是任何 Agent 工作区都必须在独立 feature 分支上主分支永远只留给人来做合并和热修复。5.2 坑二软链接和绝对路径在另一个工作区里失效这是运行大型项目的常见问题。很多仓库里会有scripts/run.sh里面写了类似ROOT_DIR$(pwd)的路径计算这没问题。但有些项目配置用的是绝对路径比如/home/you/projects/main-repo/.env换到wt-xxx工作区后就会直接报错找不到文件。Worktrunk 针对这个问题做了一个我认为很实用的功能模板同步。在根仓库里的.worktrunk/templates/目录下放.env.example、settings.local.json这类文件每次worktrunk add时它会把模板复制到新工作区并替换掉其中标记了{{WORKSPACE_NAME}}的占位符。这样 Agent 启动时拿到的就是一份有效的本地配置而不用你手动去 Worktrunk 之外再折腾一遍。5.3 坑三磁盘被重复依赖填满这个坑在 Monorepo 或者前端项目上尤其明显。假设仓库里有个packages/shared被多个子包依赖每个工作区npm install都会在各自的node_modules里生成一份完整的副本。三个工作区并行磁盘占用就是三份加上构建缓存四十个 G 的磁盘可能一周就告急。我的应对策略分几层对于轻量任务比如只改测试文件用--no-hydrate参数创建工作区。这个参数会在目录里放一个.worktrunk-nohydrate标记worktrunk list会把它标注为light状态提醒你不要在里面跑依赖安装类命令。对于需要完整依赖的任务统一先跑一次安装然后只让 Agent 在工作区里改代码和跑测试不重复安装依赖。定期执行worktrunk prune --merged-only把已经合并的分支连目录带依赖一起清理掉。经过多次实测这一招回收的磁盘占比最高能达到六个 G 以上。5.4 坑四Agent 的全局 git 配置污染提交记录还有一个比较隐蔽的问题codex CLI、Claude Code 这类工具在执行 git 提交时可能会使用全局的user.name和user.email而不是仓库本地配置。这会导致提交历史里全是同一个机器人的名字难以追溯到底是由哪个 Agent 做的改动。Worktrunk 在创建 workspace 时会在新工作区里写入本地 git configgit config user.name codex-agent git config user.email codex-agentlocal不同 Agent 的配置映射写在~/.worktrunk/agents.toml里[agents.codex] user_name codex-agent user_email codexlocal init_prompt You are working in a dedicated worktree. Do not switch branches.这个配置也在相当程度上帮 Agent 避开了自作主张切换分支的行为。我让多个 Agent 并行跑了一周提交记录干净得可以直接用来做审计。5.5 坑五Windows 路径长度限制这不算 Worktrunk 的坑而是 Git for Windows 的老毛病。当仓库路径很深加上 worktree 的wt-xxx前缀后很容易触发 Windows 的 MAX_PATH 限制260 个字符导致 Agent 无法写入部分文件。解决方式是在 Windows 上开启 Git 的长路径支持git config --global core.longpaths true或者更简单把现有仓库放到一个足够短的路径下比如C:/repo。这两种方法我都验证过核心原则是尽量不要让项目本身处在深层目录。6. 把 Worktrunk 真正嵌进 AI Agent 工作流6.1 在 Codex CLI / Claude Code 的 system prompt 里声明工作区约束单纯创建了 worktree 是不够的Agent 得知道自己在什么环境里干活。我常用的做法是在 AGENTS.md 文件里加入这些约定# Workspace Rules 1. This directory is an isolated worktree. Never run git switch or git checkout to another branch. 2. All work must be committed to the current branch: feature/user-login. 3. Do not modify files outside this directory. 4. After finishing, leave a summary in .agent-summary.md.Claude Code 会把它读取为对话上下文codex CLI 也会在启动时加载。你会发现有了这些约束后Agent 的自主行动更有边界感不太会去做一些越界操作比如把工作区切回 main。6.2 用 Worktrunk 的 wrapper 一键启动 Agent如果你不想每次手动cd再启动 CLI可以把 Worktrunk 接一层 shell 函数。我在.zshrc里加了一个函数function wt-run() { local task_name$1 shift worktrunk add --task $task_name --agent ${CURRENT_AGENT:-codex} --base main local dir$(worktrunk path $task_name) cd $dir $ }用法很简单wt-run fix-auth-refresh codex它会自动创建 workspace、切到对应目录、启动选择的 CLI。任务跑完后回到主目录执行worktrunk rm就行。6.3 给 Agent 任务加一个自动状态汇报长任务跑起来你可能不想一直盯着终端。我习惯在工作区里放一个简单的run_job.sh#!/bin/bash codex 执行 AGENTS.md 中定义的任务完成后提交代码并在 .agent-summary.md 写总结 worktrunk mark --status done --workspace $(basename $PWD)跑完后会触发worktrunk mark用来自动更新状态标记。然后主终端的worktrunk watch会立刻看到状态变为done。如果任务失败也可以改成在脚本末尾调用worktrunk mark --status failed方便人工介入。6.4 和 CI 的配合最后说一下合并策略。Worktrunk 只管工作区和分支不管合并但它的状态文件里记录了分支名和基分支信息写个小脚本可以遍历所有merged状态的分支并 push 到远端触发 CIfor ws in $(worktrunk list --status merged --json | jq -r .[].branch); do git push origin $ws done这一步由工作区元数据驱动不用自己维护分支与任务的映射表。到了这个阶段整个并行 AI Agent 工作流才算是真正完整了Agent 在独立工作区干活Worktrunk 管理生命周期CI 负责验证人工只处理异常和合并。在我自己跑了一段时间之后最大的感受是AI 编程工具本身的调用很简单难的是给它们一个良好的并发环境。Worktrunk 把 Git Worktree 从原语层提升到了任务管理层让每个 Agent 都拥有自己的一小块工地互不干扰各干各活这正是并行 AI Agent 工作流需要的底座。如果你尝试过多个 AI 编程 CLI 同时开工但不顺利我建议你先从 Git Worktree 管理这一步开始调整。