Worktrunk Agent 集成实战为 Claude Code、Codex、OpenCode、Pi 与 Gemini CLI 配置技能、活动追踪与 Worktree 隔离【免费下载链接】worktrunkWorktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows项目地址: https://gitcode.com/GitHub_Trending/wo/worktrunkWorktrunk 为每类支持的 Agent CLI 提供对应的插件但插件提供的能力取决于宿主 CLI 暴露的钩子hooks类型。本文围绕 Agent Integration 文档 展开你将学会为五种主流 AI 编码 CLI 安装/卸载 worktrunk 插件理解 / 活动状态标记如何在wt list中呈现、其底层如何以 git config 存储并被任意 CLI 复用以及 Claude Code 独有的 worktree 隔离、/wt-switch-create技能与状态栏statusline配置方案。一、能力矩阵每个插件到底给了你什么Worktrunk 的插件不是“全家桶”而是按宿主 CLI 的能力分层提供的。原文档给出的能力对照表如下完整继承自文档CapabilityClaude CodeCodexOpenCodePiGemini CLIConfiguration skill配置技能✓✓✓Activity trackingwt list中的 /✓✓✓✓✓Worktree isolationworktree 隔离✓/wt-switch-create技能*✓* 说明原文档脚注Codex 和 Gemini 也会从共享技能集加载/wt-switch-create技能但两者的技能都无法变更会话的工作目录因此该技能在那两个平台上实际上不产生效果。原文档对此的核心解释是配置技能Configuration skill是给 agent 阅读的文档帮助它完成 LLM 提交信息、hooks、排障等设置活动追踪Activity tracking用于展示哪些 worktree 里有运行中的会话worktree 隔离需要 worktree 生命周期钩子WorktreeCreate/WorktreeRemove而只有 Claude Code 暴露了这类钩子——所以 Codex、OpenCode、Pi 和 Gemini 的用户应直接调用wt switch --create和wt remove。Codex 则通过它自己的Stop和SessionEnd钩子追踪活动。换句话说五种 CLI 都能让你看到“哪个 worktree 里有 agent 在干活”但只有 Claude Code 能把 agent 的 worktree 创建/销毁行为完整接管进 worktrunk 的生命周期管理。这是理解后面所有安装与配置差异的主线。二、安装与卸载五种 CLI 逐一拆解2.1 Claude Code一条命令完成安装wt config plugins claude install对应的手动等价命令claude plugin marketplace add max-sixty/worktrunk claude plugin install worktrunkworktrunkwt config plugins claude uninstall会移除插件及其 marketplace 条目。从源码可以印证这两步的封装细节src/commands/config/plugins.rs 中定义了MARKETPLACE_SOURCE max-sixty/worktrunk与PLUGIN_SELECTOR worktrunkworktrunk两个常量handle_claude_install先检查claude plugin list --json中是否已存在同名插件已安装则短路跳过随后依次执行plugin marketplace add与plugin install卸载时则无条件执行两步plugin uninstall与marketplace remove注释明确说明“跳过某一步会让插件和 marketplace 拆散——移除插件成功而 marketplace 失败时会留下一个孤儿”。安装前还会检查claudeCLI 是否存在不存在时给出安装提示。2.2 Codexwt config plugins codex install手动等价命令codex plugin marketplace add max-sixty/worktrunk codex plugin add worktrunkworktrunkwt config plugins codex uninstall移除插件及其 marketplace 条目。实现位于 src/commands/config/codex.rs。注意 Codex 虽支持配置技能但没有worktree 隔离能力其宿主不提供WorktreeCreate类钩子因此需要 agent 新建 worktree 时直接让它执行wt switch --create branch即可。2.3 OpenCodewt config plugins opencode install该命令把活动追踪插件写入 OpenCode 的全局插件目录~/.config/opencode/plugins/worktrunk.ts尊重$OPENCODE_CONFIG_DIR与$XDG_CONFIG_HOME。wt config plugins opencode uninstall将其移除。这个插件只有一个文件却要同时兼容两代运行时——仓库中的 dev/opencode-plugin.ts 头注释解释得很清楚OpenCode 2把默认导出解码为{ id, setup }只调用setup导出OpenCode 1.16读取{ id, server }从不看setup1.16 是关键下限因为宿主从该版本开始按插件实例过滤事件。两个运行时各自忽略对方的键所以同一份安装文件在版本边界两侧都能工作1.18 还会从第二个 loader 调用setup但不传参插件对此静默返回交由server钩子兜底。事件处理逻辑与setup中的分支一致switch (event.type) { case session.status: // 状态为 idle | busy | retry await marker(directory, [set, status idle ? WAITING : WORKING]); break; case session.idle: await marker(directory, [set, WAITING]); break; case session.deleted: await marker(directory, [clear]); break; }其中marker()助手函数在插件实例所属的 worktree 目录cwd是关键字段里执行wt config state marker …且吞掉一切错误——注释原话是“wt可能不在 PATH 上或目录已不再是 worktree一个活动标记不值得为此向会话抛出错误”。这正是文档第四节“不要让标记调用失败拖垮会话”在插件层的落地。2.4 Piwt config plugins pi install该命令把活动钩子写入~/.omp/agent/hooks/pre/worktrunk.ts。路径解析规则原文档命名 profile$OMP_PROFILE或$PI_PROFILE生效时使用~/.omp/profiles/profile/agent$PI_CONFIG_DIR可以改变.omp配置根目录$PI_CODING_AGENT_DIR覆盖默认 profile 的 agent 目录。wt config plugins pi uninstall移除该钩子。对应的钩子源文件是 dev/pi-plugin.ts它注册了三个事件事件动作agent_startwt config state marker set agent_endwt config state marker set session_shutdownwt config state marker clear每次调用都通过pi.exec(wt, …, { cwd: ctx.cwd })以会话当前目录为工作目录执行并用try/catch保证“活动追踪绝不能中断宿主 Pi 会话”。2.5 Gemini CLIgemini extensions install https://github.com/max-sixty/worktrunkGemini 直接从仓库原生加载扩展仓库根目录的 gemini-extension.json 即扩展清单因此没有wt包装命令gemini extensions uninstall worktrunk将其移除。Gemini 与 Codex 一样支持配置技能与活动追踪但不提供 worktree 生命周期钩子。三、配置技能Configuration skill让 agent 自己读懂 worktrunk安装带技能的插件后agent 通过/worktrunk技能获得一份“可阅读的操作手册”可以协助完成配置 LLM 生成的提交信息[commit.generation]添加项目钩子pre-start、pre-merge、pre-commit配置 worktree 路径模板修复 shell 集成问题。Claude Code 被设计为在检测到 worktrunk 相关问题时自动加载该技能。技能本体位于仓库的 skills/worktrunk/SKILL.md其reference/目录附带 llm-commits.md、hook.md、config.md、shell-integration.md、faq.md、troubleshooting.md 等 16 篇参考文档插件打包版本在 plugins/worktrunk/skills/worktrunk/ 下内容一致。从 plugins/worktrunk/README.md 可以看到技能的典型用法引导用户在用户配置中加[commit.generation]以便wt merge自动生成提交信息、在.config/wt.toml中配置 pre-start 钩子例如建 worktree 后自动npm install。四、活动追踪/ 标记如何进入 wt list五种 CLI 的插件都通过状态标记在wt list中追踪 agent 会话。下面是wt list的真实快照摘自 tests/snapshots/integration__integration_tests__list__list_with_user_marker.snap 对应的集成测试输出原文档标注为从该快照自动生成$ wt list Branch Status HEAD± main↕ main…± Remote⇅ Commit Age Message main ^⇡ ⇡1 33323bc 1d Initial commit feature-api ↑ ↑1 1 70343f0 1d Add REST API endp… review-ui ? ↑ 1 ↑1 1 a585d6e 1d Add dashboard com… wip-docs ? – 1 33323bc 1d Initial commit ○ Showing 4 worktrees, 2 with changes, 2 ahead, hidden: Path标记含义 — agent 正在工作 — agent 在等待或空闲。Claude Code 插件的钩子映射可以完整对照 plugins/worktrunk/hooks/hooks.json钩子事件触发时机执行的 wt 命令UserPromptSubmit用户提交 promptwt -C $CLAUDE_PROJECT_DIR config state marker set Notification通知等待用户… marker set PreToolUsematcher:AskUserQuestion向用户提问前… marker set PermissionRequest请求权限时… marker set Stop一轮回答结束… marker set SessionEnd会话结束… marker clear注意两点所有命令都带-C $CLAUDE_PROJECT_DIR标记归属由工作目录解析出的分支决定且全部以|| true结尾失败不影响会话执行器是bash $CLAUDE_PLUGIN_ROOT/hooks/wt.sh这类包装脚本plugins/worktrunk/hooks/wt.shWindows 下为wt.cmd。生命周期与陈旧标记原文档所有插件在会话结束时都会清除标记如果 agent 进程在会话结束钩子执行前被 kill就会残留一个陈旧stale标记。任何时候都可以用wt config state marker clear手动清除。4.1 手动状态标记标记机制本身不依赖插件因此任意工作流都可以手动设置原文档示例完整保留$ wt config state marker set # 当前分支 $ wt config state marker set ✅ --branch feature # 指定分支 $ git config worktrunk.state.feature.marker {marker:,set_at:0} # 直接写从源码结构看标记的存储位置就是 git config 下的worktrunk.state.branch.markerJSON 值含marker与set_at字段——src/commands/config/state.rs 的模块文档把“分支标记git configworktrunk.state.branch.marker”列为“权威状态”手写/覆盖状态因此wt config state clear全量清除时会先询问确认除非--yes而state get必须能显示一切state clear会删除的东西两者在实现上被强制保持对偶。4.2 无插件的 Agent CLI 也能驱动同一套标记原文档强调活动追踪不是插件专属能力。插件只是“在宿主的事件上调用wt”而标记本身是纯 git config——因此任何能在会话生命周期事件上执行命令的 CLI都不需要 worktrunk 插件即可驱动同样的 / 标记。事件到命令的映射表如下宿主事件命令会话开始或 agent 恢复工作wt config state marker set agent 完成一轮、等待输入wt config state marker set 会话结束wt config state marker clear要写对需要抓住三点原文档要点逐条保留并补充源码印证在 worktree 内部执行命令。每个命令都从工作目录解析分支所以跑在别处的钩子会标记到错误的分支跑在仓库外则静默无效。若宿主把工作目录钉在别处请传全局-C worktree——它同时移动仓库查找与分支解析。--branch branch只单独指定分支名仓库查找仍来自工作目录这才是“钉在仓库外的调用者需要-C”的原因而不是“缺 worktree 参数”。反之本身已指定分支的命令wt switch、wt remove、wt step diff --branch已经指明了要操作的 worktree那种场景下-C的用途是换到另一个仓库而不是换一个 worktree。不要让失败的标记调用拖垮会话。在仓库外set和clear什么都不做且退出码为 0但非法的--branch或 git config 写入失败仍会返回非零而各宿主对非零钩子退出的处理不一。除非你希望问题被暴露出来否则给每个调用追加|| true或宿主的等价写法。退出时清除。会话开始设置的标记会一直存在直到被清除所以要在宿主的会话结束事件上与每个set配对一个clear——若进程先被 kill就会出现上文同样的陈旧标记。五、Worktree 隔离仅 Claude CodeClaude Code 支持让 agent 运行在隔离 worktree 中isolation: worktree。默认情况下 Claude Code 用git worktree add创建这些 worktree。worktrunk 插件则用WorktreeCreate和WorktreeRemove钩子把这条路径改道到wt switch --create与wt remove于是 agent 创建的 worktree 自动获得 worktrunk 的命名规范、项目钩子与生命周期管理。plugins/worktrunk/hooks/hooks.json 中两条钩子的完整实现值得逐字细读# WorktreeCreate从 stdin 的 JSON 读取 name创建后回传 path name$(jq -er .name) || exit 1 cd ${CLAUDE_PROJECT_DIR:-.} || exit 1 bash $CLAUDE_PLUGIN_ROOT/hooks/wt.sh switch --create $name --no-cd --formatjson | jq -er .path # WorktreeRemove从 stdin 的 JSON 读取 worktree_path前台移除 p$(jq -er .worktree_path) || exit 1 [ -e $p/.git ] || exit 0 bash $CLAUDE_PLUGIN_ROOT/hooks/wt.sh -C $p remove --foreground $p几个设计细节创建钩子以--no-cd --formatjson调用wt switch仅从 stdout 的 JSON 中取path字段回传给 Claude Code状态行走 stderr不污染结果移除钩子先检查path/.git是否存在不存在就exit 0容忍空操作。插件 READMEplugins/worktrunk/README.md也提示worktree 生命周期钩子依赖jq安装插件前需确认可用。六、/wt-switch-create技能仅 Claude Code/wt-switch-create [branch] [repo] [-- task]让你在不离开当前会话的情况下开启新任务创建 worktree → 把会话切进去 → 执行任务三个参数都可省略。新建的 worktree 出现在wt list中事后可用wt merge/wt remove合并或移除。技能定义见 skills/wt-switch-create/SKILL.md其要点参数语法[branch] [repo] [-- task]--之前的 token 中路径形态/、~、./、../开头识别为 repo其余识别为分支名docs是分支名绝不是docs/目录首选路径是调用EnterWorktree({name: branch})——由于插件的WorktreeCreate钩子会把它落到wt switch --create结果就是标准布局的普通 wt worktreerepo.branch/且无需用户确认若带 repo 参数或上一步失败则退化为wt -C repo switch --create branch --no-cd --formatjson拿path字段再EnterWorktree({path})会话中途迁移未提交工作时EnterWorktree前后分别git stash push -u/git stash popstash 跨 worktree 共享清理规则从未被会话触碰无文件变更、无提交的 worktree 会随会话结束被连同分支一起清理写入过内容的则保留走正常的wt merge/wt remove branch。七、状态栏Statusline仅 Claude Codewt list statusline --formatclaude-code输出一行状态供 Claude Code 状态栏使用。由于 Claude Code 在后台运行该命令偶尔 1–2 秒的 CI 抓取延迟对用户不可见。一行输出的构成原文档示例~/w/myproject.feature-auth ! 42 -8 ↑3 ⇡1 #3035 Opus 65% 1.4×(10am–3pm)其中 worktree 状态部分来自与wt list相同的单元格Claude Code 通过 stdin 传入的 JSON 则补充了模型名、 65%上下文占用表与速率限制提示。配置方式原文档——在~/.claude/settings.json中加入{ statusLine: { type: command, command: wt list statusline --formatclaude-code } }这一步也可以交给 worktrunk 完成wt config plugins claude install-statusline实现见 src/commands/config/plugins.rs 的handle_claude_install_statusline。它先检测是否已配置已配置则短路再定位settings.json$CLAUDE_CONFIG_DIR或~/.claude读取现有 JSON 并合并statusLine键后原子写回——不会覆盖你已存在的其他设置。八、小结与验证清单能力选择想要 worktree 隔离与/wt-switch-create→ Claude Code只需要活动标记 → 五种 CLI 的插件任选甚至无插件也能用会话事件钩子驱动安装入口Claude/Codex/OpenCode/Pi 统一走wt config plugins name install各有 uninstall 对称命令Gemini 走gemini extensions install标记存储git configworktrunk.state.branch.markerset/clear幂等且可在仓库外安全执行退出码 0但非法--branch与写入失败仍会非零——钩子里记得|| true陈旧标记进程被 kill 时残留wt config state marker clear一键清除状态栏wt list statusline --formatclaude-code可手动或经install-statusline写入~/.claude/settings.json。如需进一步深入可按文中路径继续查看钩子清单 plugins/worktrunk/hooks/hooks.json、插件管理命令 src/commands/config/plugins.rs、状态与标记存储 src/commands/config/state.rs、OpenCode 双运行时插件 dev/opencode-plugin.ts、Pi 钩子 dev/pi-plugin.ts以及行为快照 tests/snapshots/integration__integration_tests__list__list_with_user_marker.snap。【免费下载链接】worktrunkWorktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows项目地址: https://gitcode.com/GitHub_Trending/wo/worktrunk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考