wt-switch-create

参数：$ARGUMENTS。语法：[<branch>] [<repo>] [-- <task>]。

• branch — 可选；新工作树的分支名称。省略时， 按照下文步骤 1 选择。
• repo — 可选路径或名称；在此仓库中创建工作树，而不是在会话当前所在的仓库中创建。
• task — 可选；在新工作树中要执行的操作。不指定任务则进入 工作树并等待。

-- 之前的标记是分支和／或仓库。形似路径的标记 （以 /、~、./ 或 ../ 开头）是仓库。裸名称可能是分支，也可能是仓库， 需要根据情况判断。如果当前仓库已有同名分支，则它是分支，wt switch 本身也是如此。否则，如果用户存放仓库的位置（当前仓库旁边，或 ~/workspace 这样的工作区目录）存在同名 git 仓库，则它是仓库；若不存在，则它是分支（docs 是分支，而不是当前仓库的 docs/ 目录）。如果名称被识别为仓库，则后续使用其绝对路径：步骤 3 中的 <repo> 应是该路径，而不是裸标记。两个标记若都被识别为分支，则不符合语法——请询问用户。如果没有 --，根据任务从哪里开始判断：开头被识别为分支名称（fix-auth）或仓库的标记会被视为相应参数，剩余部分是任务；否则，整个输入都视为任务（fix the parser bug 没有形似分支的开头，因此全部是任务）。

/wt-switch-create my-feature -- fix the parser bug
/wt-switch-create -- fix the parser bug
/wt-switch-create my-feature ~/workspace/other-repo -- fix the parser bug
/wt-switch-create my-feature

要做的事

每次调用都必须先创建工作树，再进行任何其他工作。调用本身就是创建工作树的明确请求；即使是研究或只读任务，也照样创建工作树。

1. 如果没有提供分支名称，则选择一个新名称：名称要简短，根据任务确定， 并与现有工作树名称保持一致；如果是在会话中途，则根据要迁移的工作选择名称；如果没有可据以命名的内容，请询问。

2. 未提供仓库参数时，在一次调用中创建并进入工作树： EnterWorktree({name: "<branch>"})。Worktrunk 的 WorktreeCreate hook 会为新分支运行 wt switch --create，或为现有分支运行 wt switch，并在需要时创建其检出目录。结果是普通的 wt 工作树，用户不会看到确认提示。成功后，执行任务（如果没有任务文本，则确认已准备就绪并等待）。

   如果在会话中途操作，请将未提交的工作一并迁移：在调用 EnterWorktree 前运行 git stash push -u，之后运行 git stash pop——该调用会将会话的根目录切换到新工作树，而 stash 在各工作树间共享。

3. 其他情况，使用 wt 创建并通过路径进入工作树。 以下两种情况会进入此步骤：提供了仓库参数（步骤 2 无法针对该仓库），或步骤 2 失败且错误提示为 Already in a worktree session。使用 Bash 调用创建（若是当前仓库，则省略 -C <repo>）：

   wt -C <repo> switch --create <branch> --no-cd --format=json
   

   标准输出为 JSON，其中 path 字段是工作树的绝对路径（状态行会输出到标准错误）。如果提示 Branch <branch> already exists：若分支由用户指定，则不带 --create 重新运行（这会进入该分支，并在工作树不存在时创建工作树）；若名称由步骤 1 选择，则换一个名称后重新运行。其他任何失败（不是 git 仓库、名称无效）：报告错误并停止。

   如果提供了仓库参数，接下来单独使用 Bash 调用运行 cd <repo>。 EnterWorktree 只会在当前工作目录所属的仓库内切换根目录，而 Worktrunk 的 PermissionRequest hook 仅会为同一仓库的 wt 工作树，回答该调用所请求的确认。如果 cd 报告 Shell cwd was reset，则无法访问该仓库：跳过进入步骤，并按照下文 无法访问 的说明交接。

   然后调用 EnterWorktree({path: "<path from the JSON>"})。

   如果提供了仓库参数，在会话开始于新工作树中工作之后（已进入，或通过下文的恢复步骤使用 cd 进入），在执行任务前读取该仓库根目录下存在的 CLAUDE.md 和 AGENTS.md。Claude Code 会将启动时所在仓库的根目录指令保留在上下文中，并且只加载新仓库中更深层级的指令文件，因此，在本次会话剩余时间内，新仓库的根目录文件会取代启动时仓库的根目录文件。

   • 已接受 → 会话已在该工作树中重新定位。执行任务（如果没有任务文本，则确认已就绪并等待）。
   • 工具错误 — 工具已运行并返回错误（Cannot enter worktree: …）→ 可妥善处理；没有任何内容被移动，一种恢复方法适用于所有情况。常见原因是会话已位于某个工作树中（或使用了固定 Agent），这会将进入范围限制在当前仓库的 .claude/worktrees/，甚至不包括同一仓库中的 wt 兄弟目录。恢复时要检查的是能否 cd 进入该工作树；如果它位于允许的目录中，就可以进入。因此，执行 cd <path> 并查看结果：
     • 没有出现 Shell cwd was reset 提示 → 已成功进入；该工作树可访问。在其中工作，但单独执行 cd 不会将重新定位记录为受跟踪状态，因此跨轮次（以及在衍生的子 Agent 中）当前工作目录可能会恢复为会话启动时所在的工作树；请使用 git -C <path> / wt -C <path> 固定命令，而不要指望 cd 持续生效。
     • 出现 Shell cwd was reset → 无法访问。 停止并请用户让重置 cd 的目录变为可访问：将同时包含仓库及其工作树的父目录（例如 ~/workspace）添加到 permissions.additionalDirectories（长期生效，每个会话均适用），或对其运行 /add-dir（仅限本会话）。然后从该 cd 继续。不要在每条命令执行时 cd 都被重置的情况下，反复尝试绝对路径。
   • 已拒绝 — 调用本身被拒绝，没有工具错误 → 无论拒绝提示如何措辞，这都是用户对 Claude Code 显示的、关于进入 .claude/worktrees/ 之外工作树的确认请求所作的答复；但如果无法询问用户（拒绝提示称会话无法发起询问），则不能据此得出任何结论——请采用上述恢复方法。根据用户的答复：刚创建的工作树 wt 仍然存在；只是没有进入其中。如果你已移入仓库，请先 cd 回去，然后报告该工作树的路径并询问如何继续，因为通过 cd 访问它会违背用户的答复。

清理

该工作树是一个普通的 worktrunk 工作树：它会显示在 wt list 中，可像其他工作树一样使用 wt merge 合并，或使用 wt remove <branch> 删除。不要擅自删除。

如果会话从未操作过第 2 步创建的工作树（没有更改文件，也没有提交），则会话结束时会清理该工作树及其分支；任何写入其中的内容都会使其保留。第 3 步创建的工作树始终保留。如果用户要求在会话中途离开，ExitWorktree({action: "keep"}) 会将会话返回其原始目录； ExitWorktree 无法删除通过 path 进入的工作树，因此这类工作树始终要使用 wt remove <branch> 删除。

范围

该命令的职责范围是一个工作树（如果指定了仓库，则位于该仓库中）以及其中要求执行的任务。提交、推送和合并仍须分别获得用户的明确许可。