worktrunk

Worktrunk

帮助用户使用 Worktrunk，这是一款用于管理 git worktree 的命令行工具。

可用文档

参考文件同步自 worktrunk.dev 文档：

• reference/config.md：用户和项目配置（LLM、钩子、命令默认值）
• reference/hook.md：钩子类型、时机和执行顺序
• reference/switch.md、merge.md、list.md 等：命令文档
• reference/extending.md：别名、多步管道、自定义子命令和模板展开注意事项（两遍 {% raw %} 延迟处理、for-each 配方）
• reference/llm-commits.md：LLM 提交消息生成
• reference/tips-patterns.md：实用配方——别名、分支级变量、每个 worktree 一个开发服务器、并行 Agent 模式
• reference/shell-integration.md：Shell 集成调试
• reference/troubleshooting.md：LLM 和钩子的故障排除（针对 Claude）

查看特定命令的选项，请运行 wt <command> --help。配置请参阅下方的工作流程。

命令操作的 worktree

wt 根据工作目录查找 仓库，并根据命令自身的参数选择 worktree。两条规则适用于所有情况：

1. 指定分支的命令也就指定了对应的 worktree。 worktree 通过分支名称寻址，因此无论从哪个 worktree 运行，wt switch <branch>、wt remove <branch>、wt step diff --branch <branch> 和 wt config state marker set --branch <branch> 都会操作该分支的 worktree。对于分支无法标识的情况，每个此类参数也接受 worktree 自身的路径，例如同一分支的第二个检出，或游离 worktree（marker 仍会拒绝后者，因为它按分支名称记录状态）。

2. -C <path> 会更改工作目录，而不是 worktree 选择。 当仓库查找有误时使用它：目标是另一个仓库；命令操作当前 worktree 且不接受分支参数（wt merge、wt step rebase|squash|push——这些命令的 [TARGET] 是合并目标，而不是 worktree）；或者调用方的工作目录不在任何仓库中，例如宿主固定在其他位置的 Agent 钩子。

在分支参数上叠加 -C，等于重复指定同一个 worktree。在仓库的 alpha worktree 中，且该仓库也有 beta 时：

wt step diff --branch beta                    # ✓ the branch argument selects the worktree
wt -C ../repo.beta step diff --branch beta    # ✗ says beta twice

wt switch --create beta                       # ✓ --base already defaults to the default branch
wt -C ../repo switch --create beta            # ✗ -C adds nothing; you are already in that repo

两种配置

Worktrunk 使用两个配置文件，作用范围和权限模型各不相同：

用户配置（~/.config/worktrunk/config.toml，绝不会提交到 git）保存个人偏好：LLM 集成、worktree 路径模板、命令设置和用户钩子。应谨慎处理——提出更改并征得同意后再编辑；绝不要代替用户安装工具；并保留文件现有的结构和注释。参见 reference/config.md。

项目配置（<repo>/.config/wt.toml，会提交到 git）保存团队级自动化：worktree 生命周期钩子（pre-start、pre-merge 等）。可主动编辑——更改会纳入版本控制，并可通过 git 撤销。请说明每个钩子的用途；添加破坏性命令（rm -rf、DROP TABLE）、将网络获取内容通过管道传给 shell 的命令，或 sudo 之前，请警告用户。参见 reference/hook.md。

有些请求会涉及两者：提交消息生成属于用户配置，而团队质量检查属于项目配置。

核心工作流程

设置提交消息生成（用户配置）

检测已安装的工具（which claude codex opencode llm aichat）；如果一个都没有，建议使用 Claude Code。从 reference/llm-commits.md 中取用所选工具的准确命令，提出 [commit.generation] 更改，并在获得批准后应用（如果配置不存在，先运行 wt config create）。验证时，wt step commit --dry-run 会呈现提示词、运行 LLM，并打印消息而不提交。

配置项目钩子

根据命令应在何时运行以及是否可以阻塞来选择钩子类型 — reference/hook.md 列出了全部十种（5 个事件 × 前/后）及其运行时机和典型用途。

根据项目自身的配置（package.json 脚本、Cargo.toml、pyproject.toml）确定命令，并在添加前验证它们可以运行。

当新钩子必须等待现有钩子完成时，将条目转换为流水线；命名表中的独立命令会并发运行：

# Pipeline: install completes before migrate starts
[[pre-start]]
install = "npm install"

[[pre-start]]
migrate = "npm run db:migrate"

# Concurrent: independent commands in one table
[pre-start]
install = "npm install"
env = "cp .env.example .env"

使用 wt switch --create test-hooks 进行测试。

常见任务参考

用户配置任务

• 设置提交消息生成 → reference/llm-commits.md
• 自定义工作树路径 → reference/config.md#worktree-path-template
• 自定义提交模板 → reference/llm-commits.md#prompt-templates
• 配置命令默认值 → reference/config.md#command-config
• 设置个人钩子 → reference/config.md#user-hooks

项目配置任务

• 为新项目设置钩子 → reference/hook.md
• 向现有配置添加钩子 → reference/hook.md#hook-forms
• 使用模板变量 → reference/hook.md#template-variables
• 将开发服务器 URL 添加到列表 → reference/config.md#dev-server-url

别名与多工作树任务

• 创建 wt 别名 → reference/extending.md#aliases
• 在每个工作树中运行命令 → reference/step.md#wt-step-for-each
• 对每个工作树执行变基（up-style）→ reference/extending.md#recipe-rebase-every-worktree-onto-its-upstream
• 将模板传递给嵌套的 wt 命令 → reference/extending.md#nesting-templates

关键命令

# View all configuration
wt config show

# Create initial user config (LLM/commit setup: see reference/llm-commits.md)
wt config create

# Full config reference (subcommands, templates, env vars)
wt config --help

非交互式会话中的钩子审批

Worktrunk 在用户明确批准项目的钩子或别名之前，绝不会运行它们。.config/wt.toml 中的命令是任意 shell 代码，随仓库一同提供，而用户可能刚刚克隆了该仓库。因此，首次运行时，Worktrunk 会显示每条命令并等待用户批准 — 不受信任的 .config/wt.toml 无法静默执行任何内容。审批按项目存储在 ~/.config/worktrunk/approvals.toml 中；每当命令模板发生变化时，系统都会重新提示审批，因此钩子无法在获批后被替换为其他命令。

运行 wt merge、wt switch 或其他会触发钩子的命令时，Agent 会遇到类似以下错误：

▲ cargo-difftest needs approval to execute 1 command:
○ post-merge install:
  cargo install --path .
✗ Cannot prompt for approval in non-interactive environment
↳ To skip prompts in CI/CD, add --yes; to pre-approve commands, run wt config approvals add --yes

解决方法是由用户亲自作出信任决定：

• wt config approvals add — 交互式提示，用户可在命令保存到 ~/.config/worktrunk/approvals.toml 前逐条审阅。每个项目运行一次；审批会在后续调用中持续有效，直到命令模板发生变化或项目迁移。这是推荐的做法 — 用户会审阅并同意将要运行的确切命令。

作为 Agent 调用时，请停止并升级给用户处理。 批准项目钩子属于安全决策，涉及是否信任该仓库在用户的计算机上运行任意命令 — 这项决定应由用户作出，而非 Agent。请告知用户运行 wt config approvals add 并自行审阅命令。不要擅自使用 --yes：对于被阻止的命令，它会跳过本次调用的审批门槛；而 wt config approvals add --yes 会记录项目声明的所有命令，且无人审阅。两者都是为 CI/CD 流水线和已自行控制钩子内容的容器准备的；它们都不是交互式 Agent 用来绕过审批提示的捷径。

高级：Agent 交接

当用户要求在后台会话中生成一个带 Agent 的 worktree（“为……生成一个 worktree”“交接给另一个 Agent”）时，使用 reference/tips-patterns.md#agent-handoffs 中的 tmux 或 Zellij 命令，并将其中的 claude 替换为你正在运行的 CLI，同时遵循该部分关于 OpenCode 的 run 等子命令应放在哪里的说明。

要求（必须全部满足）：

• 用户明确要求生成或交接
• 用户正在使用受支持的复用器（检查 $TMUX / $ZELLIJ）
• 用户的项目说明（CLAUDE.md 或 AGENTS.md）或明确提示词授权使用此模式

常规 worktree 操作中不要使用此模式。

并行子 Agent（单个 Claude Code 会话）

若要在一个 Claude Code 会话中生成多个各自在独立 worktree 中工作的子 Agent——不使用终端复用器，也不需要其他窗格中的人员——请先由父会话预先启动每个 worktree，并将路径传入子 Agent 提示词：

wt switch --create <branch> --no-cd

然后调用 Agent 工具，不要使用 isolation: "worktree"，并在提示词中指定路径：

You are working in `/abs/path/to/myproject.<branch>` on branch `<branch>`.
All edits must stay in that worktree.

--no-cd 会跳过父会话无法使用的 shell 集成 cd 脚本。只有在用户或项目的钩子都不会配置 worktree，且每个子 Agent 都会自行执行构建/测试步骤（例如 cargo run -- hook pre-merge --yes）时，才添加 --no-hooks——如果跳过了会安装依赖项或链接被 git 忽略的构建环境的 pre-start 钩子，子 Agent 拿到的 worktree 就无法构建。若保留钩子，必须已批准项目的钩子命令：父会话无法提示，因此 .config/wt.toml 中未经批准的命令会导致创建中止——参见上文的非交互式会话中的钩子审批。

不要为此使用 Agent { isolation: "worktree" }。Claude Code 会将其内部 Agent ID 作为 name 传给 WorktreeCreate 钩子，因此 wt 会在临时分支上将 worktree 创建为 myproject.agent-<id>。如果子 Agent 随后在此基础上创建功能分支，就会导致路径不规范、分支孤立，并且启动后钩子会针对错误的分支触发。使用 wt switch --create 预先创建 worktree，可确保路径、分支和钩子目标保持一致。