worktrunk

Worktrunk

帮助用户使用 Worktrunk，一个用于管理 Git 工作树的 CLI 工具。

可用文档

参考文件从 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：实用配方——别名、每分支变量、每个工作树的开发服务器、并行代理模式
• reference/shell-integration.md：Shell 集成调试
• reference/troubleshooting.md：LLM 和钩子的故障排除（Claude 专用）

有关命令特定选项，请运行 wt <command> --help。有关配置，请遵循以下工作流程。

两种配置类型

Worktrunk 使用两个具有不同范围和权限模型的配置文件：

用户配置（~/.config/worktrunk/config.toml，永不提交到 Git）保存个人偏好：LLM 集成、工作树路径模板、命令设置、用户钩子。谨慎对待——提出更改并在获得同意后编辑，切勿代表用户安装工具，并保留文件的现有结构和注释。参见 reference/config.md。

项目配置（<repo>/.config/wt.toml，提交到 Git）保存团队范围的自动化：工作树生命周期的钩子（pre-start、pre-merge 等）。主动编辑——更改通过 Git 进行版本控制和可逆。注释每个钩子存在的原因，并在添加破坏性命令（rm -rf、DROP TABLE）、通过管道传输到 Shell 的网络获取或 sudo 之前警告用户。参见 reference/hook.md。

某些请求跨越两者：提交信息生成是用户配置，而团队的质量检查是项目配置。

核心工作流程

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

检测已安装的工具（which claude codex llm aichat）；如果没有，推荐 Claude Code。从 reference/llm-commits.md 中获取所选工具的确切命令，提出 [commit.generation] 更改，并在批准后应用（如果尚无配置，先运行 wt config create）。要验证，wt step commit --dry-run 会渲染提示、运行 LLM 并打印消息而不提交。

配置项目钩子

根据命令应何时运行以及是否可能阻塞来选择钩子类型（10 种类型：5 个事件 × pre/post——完整参考见 reference/hook.md）：

• 后续步骤需要的依赖和环境文件 → pre-start（阻塞创建）
• 开发服务器、长时间构建、缓存复制 → post-start（后台）
• 格式化程序、linter、类型检查 → pre-commit
• 合并前必须通过的测试 → pre-merge
• CI 触发器、通知 → post-commit
• 部署 → post-merge
• 分支解析前的设置 / 终端 IDE 更新 → pre-switch / post-switch
• 移除前后的清理（保存工件；停止服务器、移除容器） → pre-remove / post-remove

从项目本身（package.json 脚本、Cargo.toml、pyproject.toml）推导命令，并在添加前验证它们能运行。

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

# 管道：install 在 migrate 之前完成
[[pre-start]]
install = "npm install"

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

# 并发：一个表中的独立命令
[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#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 风格） → reference/extending.md#recipe-rebase-every-worktree-onto-its-upstream
• 将模板变量延迟到嵌套的 wt 命令 → reference/extending.md#deferring-expansion-to-a-nested-wt-command

关键命令

# 查看所有配置
wt config show

# 创建初始用户配置（LLM/提交设置：参见 reference/llm-commits.md）
wt config create

# 完整配置参考（子命令、模板、环境变量）
wt config --help

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

Worktrunk 在用户明确批准之前永远不会运行项目的钩子或别名。.config/wt.toml 中的命令是用户可能刚刚克隆的仓库中提供的任意 Shell 代码，因此在首次运行时 Worktrunk 会显示每个命令并等待用户批准——不受信任的 .config/wt.toml 不能静默执行任何操作。批准按项目存储在 ~/.config/worktrunk/approvals.toml 中，并在命令模板更改时重新提示，因此钩子在批准后不能被替换为不同的命令。

运行 wt merge、wt switch 或其他触发钩子的命令的代理会遇到如下错误：

▲ cargo-difftest 需要批准才能执行 1 个命令：
○ post-merge install:
  cargo install --path .
✗ 无法在非交互式环境中提示批准
↳ 要跳过 CI/CD 中的提示，添加 --yes；要预先批准命令，运行 wt config approvals add

解决方案是让用户自己做出信任决定：

• wt config approvals add ——交互式提示，用户审查每个命令，然后将其存储到 ~/.config/worktrunk/approvals.toml。每个项目运行一次；批准在调用之间持续存在，直到命令模板更改或项目移动。这是推荐的方式——用户审查并同意将要运行的命令。

当作为代理调用时，停止并上报给用户。 批准项目的钩子是一个安全决策，关于是否应信任此仓库在用户机器上运行任意命令——该决策属于用户，而不是代理。告诉用户运行 wt config approvals add 并让他们审查命令。不要代表用户运行 --yes：它会跳过该调用的批准门，因此用它来解除命令阻塞会破坏保护。--yes 用于已经控制自己钩子内容的 CI/CD 管道；它不是交互式代理静默批准提示的快捷方式。

高级：代理交接

当用户请求在后台会话中生成一个带有代理的工作树（“为...生成工作树”、“交接给另一个代理”）时，使用适合其终端复用器的模式。将 <agent-cli> 替换为您正在运行的 CLI：claude 用于 Claude Code，'opencode run' 用于 OpenCode。

tmux（检查 $TMUX 环境变量）：

tmux new-session -d -s <branch-name> "wt switch --create <branch-name> -x <agent-cli> -- '<task description>'"

Zellij（检查 $ZELLIJ 环境变量）：

zellij run -- wt switch --create <branch-name> -x <agent-cli> -- '<task description>'

要求（必须全部满足）：

• 用户明确请求生成/交接
• 用户处于支持的复用器中（tmux 或 Zellij）
• 用户的项目说明（CLAUDE.md 或 AGENTS.md）或显式提示授权此模式

不要将此模式用于正常的工作树操作。

示例（tmux，Claude Code）：

tmux new-session -d -s fix-auth-bug "wt switch --create fix-auth-bug -x claude -- \
  '登录会话在 5 分钟后过期。找到会话超时配置并将其延长到 24 小时。'"

示例（Zellij，OpenCode）：

zellij run -- wt switch --create fix-auth-bug -x 'opencode run' -- \
  '登录会话在 5 分钟后过期。找到会话超时配置并将其延长到 24 小时。'

并行子代理（单个 Claude Code 会话）

要从一个 Claude Code 会话中生成多个子代理，每个子代理在自己的工作树中工作——无需终端复用器，无需另一个窗格中的人——从父级预先启动每个工作树，并将路径传递给子代理提示：

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

然后调用 Agent 工具不带 isolation: "worktree"，在提示中命名路径：

你正在分支 `<branch>` 上的 `/abs/path/to/worktrunk.<branch>` 中工作。
所有编辑必须保留在该工作树中。

--no-cd 跳过父级无法使用的 Shell 集成 cd 脚本；--no-hooks 适用于每个子代理将运行自己的构建/测试步骤（例如 cargo run -- hook pre-merge --yes）且不需要每个工作树重复 post-start 设置的情况。

不要为此使用 Agent { isolation: "worktree" }。Claude Code 将其内部代理 ID 作为 name 传递给 WorktreeCreate 钩子，因此 wt 在一次性分支上创建工作树为 worktrunk.agent-<id>。如果子代理随后在其上创建功能分支，最终会得到非规范路径、孤立分支以及针对错误分支触发的 post-start 钩子。使用 wt switch --create 预先创建可保持路径、分支和钩子目标一致。