Arguments: $ARGUMENTS. Grammar: [<branch>] [<repo>] [-- <task>].
- branch — optional; the branch name for the new worktree. When omitted,
pick one (step 1 below).
- repo — optional path; create the worktree in this repo instead of the
session's current one.
- task — optional; what to do inside the new worktree. No task means enter
the worktree and wait.
Tokens before the -- are the branch and/or repo: a path-shaped token
(starting with /, ~, ./, or ../) is the repo; any other token is the
branch (docs is a branch name, never the docs/ directory). More than one
branch-shaped token before a -- doesn't fit the grammar — ask. Without a
--, judge where the task starts: leading tokens that read as a branch name
(fix-auth) or a repo path are consumed as such, and the rest is the task;
otherwise the whole input is the task (fix the parser bug has no
branch-shaped lead — all task).
/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
What to do
Creating the worktree comes first on every invocation, before any other work.
The invocation is itself the explicit request to create it; a research or
read-only task gets one all the same.
Pick the branch name if none was given: short, from the task and
consistent with existing worktree names, or, mid-session, from the work
being moved; with nothing to derive from, ask.
With no repo argument, create and enter in one call:
EnterWorktree({name: "<branch>"}). Worktrunk's WorktreeCreate hook runs
wt switch --create, so the result is an ordinary wt worktree in the
default layout, and the user sees no confirmation prompt. On success,
do the task (or, with no task text, confirm it's ready and wait).
Mid-session, carry uncommitted work across: git stash push -u before the
EnterWorktree call, then git stash pop after — the call re-roots the
session into the new worktree, and the stash is shared across worktrees.
Otherwise create it with wt and enter by path. Two cases reach here: a
repo argument, which step 2 can't target, and a failed step 2, whose error
says which — ✗ Branch <branch> already exists, or Already in a worktree session. Create with a Bash call (omit -C <repo> for this repo):
wt -C <repo> switch --create <branch> --no-cd --format=json
Stdout is JSON whose path field is the worktree's absolute path (status
lines go to stderr). On Branch <branch> already exists: if the user named
the branch, rerun without --create (it enters the branch, creating its
worktree if missing); if step 1 picked the name, pick another and rerun. Any
other failure (not a git repo, invalid name): report it and stop.
Then call EnterWorktree({path: "<path from the JSON>"}).
- Accepted → the session is re-rooted in the worktree. Do the task (or,
with no task text, confirm it's ready and wait).
- Tool error — the tool ran and returned an error (
Cannot enter worktree: …) → graceful; nothing moved, and one recovery covers them
all. Common causes: the cwd resolves to no git repo (e.g. a non-git
parent like ~/workspace that only holds repos, as in a background job)
or to a different repo than the target; or the session is already rooted
in a worktree (or is a pinned agent), which limits entry to the current
repo's .claude/worktrees/ and excludes even a same-repo wt sibling.
The recovery test is whether you can cd into the worktree, which works
when it's inside an allowed directory. So cd <path> and read the
result:
- no
Shell cwd was reset notice → it stuck; the worktree is reachable.
Work there, but a bare cd is not a tracked re-root, so the cwd can
revert to the session's launch worktree across turns (and in spawned
subagents); pin commands with git -C <path> / wt -C <path> rather
than trusting the cd to persist.
Shell cwd was reset → not reachable. Stop and ask the user to make it
reachable: add the repo, or a parent like ~/workspace, to
permissions.additionalDirectories (durable, every session), or run
/add-dir <path> (this session). Then continue. Don't grind through
absolute paths with cd resetting on every command.
- Denied — the call itself was refused, with no tool error → however
the denial is worded, it is the user's answer to the confirmation Claude
Code shows for entering a worktree outside
.claude/worktrees/, unless
there was no user to ask (the denial says the session couldn't prompt),
which decides nothing — take the recovery above. On the user's answer:
the worktree wt just created still exists; only the entry didn't
happen. Report its path and ask how to proceed, since reaching it
through cd would override that answer.
Cleanup
The worktree is a normal worktrunk worktree: it shows up in wt list and is
merged or removed with wt merge / wt remove <branch> like any other. Don't
remove it unprompted.
A worktree from step 2 that the session never touched — no changed files, no
commits — is cleaned up when the session ends, branch included; anything
written into it keeps it. A worktree from step 3 always stays. If the user asks
to leave mid-session, ExitWorktree({action: "keep"}) returns the session to
its original directory;
ExitWorktree cannot remove a worktree entered by path, so removing one of
those is always wt remove <branch>.
Scope
The command's mandate is ONE worktree (in the named repo, if one was given)
and the requested task inside it. Commits, pushes, and merges still each
require explicit user permission.
1---
2name: wt-switch-create
3description: Create a new worktrunk worktree (optionally in another repo) and switch this session's working directory into it. Use when launching a session that should work in its own worktree.
4argument-hint: "[<branch>] [<repo>] [-- <task>]"
5license: MIT OR Apache-2.0
6compatibility: Requires the `wt` CLI (https://worktrunk.dev)
7metadata:
8 source: https://skillmd.com/skills/max-sixty/wt-switch-create
9---
10
11Arguments: `$ARGUMENTS`. Grammar: `[<branch>] [<repo>] [-- <task>]`.
12
13- **branch** — optional; the branch name for the new worktree. When omitted,
14 pick one (step 1 below).
15- **repo** — optional path; create the worktree in this repo instead of the
16 session's current one.
17- **task** — optional; what to do inside the new worktree. No task means enter
18 the worktree and wait.
19
20Tokens before the `--` are the branch and/or repo: a path-shaped token
21(starting with `/`, `~`, `./`, or `../`) is the repo; any other token is the
22branch (`docs` is a branch name, never the `docs/` directory). More than one
23branch-shaped token before a `--` doesn't fit the grammar — ask. Without a
24`--`, judge where the task starts: leading tokens that read as a branch name
25(`fix-auth`) or a repo path are consumed as such, and the rest is the task;
26otherwise the whole input is the task (`fix the parser bug` has no
27branch-shaped lead — all task).
28
29```
30/wt-switch-create my-feature -- fix the parser bug
31/wt-switch-create -- fix the parser bug
32/wt-switch-create my-feature ~/workspace/other-repo -- fix the parser bug
33/wt-switch-create my-feature
34```
35
36## What to do
37
38Creating the worktree comes first on every invocation, before any other work.
39The invocation is itself the explicit request to create it; a research or
40read-only task gets one all the same.
41
42<!-- Maintainers: rationale.md (same directory) covers the harness rules and
43design choices behind this — read it before re-adding guards or routes. -->
44
451. **Pick the branch name** if none was given: short, from the task and
46 consistent with existing worktree names, or, mid-session, from the work
47 being moved; with nothing to derive from, ask.
48
492. **With no repo argument, create and enter in one call:**
50 `EnterWorktree({name: "<branch>"})`. Worktrunk's `WorktreeCreate` hook runs
51 `wt switch --create`, so the result is an ordinary `wt` worktree in the
52 default layout, and the user sees no confirmation prompt. On success,
53 do the task (or, with no task text, confirm it's ready and wait).
54
55 Mid-session, carry uncommitted work across: `git stash push -u` before the
56 `EnterWorktree` call, then `git stash pop` after — the call re-roots the
57 session into the new worktree, and the stash is shared across worktrees.
58
593. **Otherwise create it with `wt` and enter by path.** Two cases reach here: a
60 repo argument, which step 2 can't target, and a failed step 2, whose error
61 says which — `✗ Branch <branch> already exists`, or `Already in a worktree
62 session`. Create with a `Bash` call (omit `-C <repo>` for this repo):
63
64 ```
65 wt -C <repo> switch --create <branch> --no-cd --format=json
66 ```
67
68 Stdout is JSON whose `path` field is the worktree's absolute path (status
69 lines go to stderr). On `Branch <branch> already exists`: if the user named
70 the branch, rerun without `--create` (it enters the branch, creating its
71 worktree if missing); if step 1 picked the name, pick another and rerun. Any
72 other failure (not a git repo, invalid name): report it and stop.
73
74 Then call `EnterWorktree({path: "<path from the JSON>"})`.
75
76 - **Accepted** → the session is re-rooted in the worktree. Do the task (or,
77 with no task text, confirm it's ready and wait).
78 - **Tool error** — the tool ran and returned an error (`Cannot enter
79 worktree: …`) → graceful; nothing moved, and one recovery covers them
80 all. Common causes: the cwd resolves to no git repo (e.g. a non-git
81 parent like `~/workspace` that only holds repos, as in a background job)
82 or to a different repo than the target; or the session is already rooted
83 in a worktree (or is a pinned agent), which limits entry to the current
84 repo's `.claude/worktrees/` and excludes even a same-repo `wt` sibling.
85 The recovery test is whether you can `cd` into the worktree, which works
86 when it's inside an allowed directory. So `cd <path>` and read the
87 result:
88 - no `Shell cwd was reset` notice → it stuck; the worktree is reachable.
89 Work there, but a bare `cd` is not a tracked re-root, so the cwd can
90 revert to the session's launch worktree across turns (and in spawned
91 subagents); pin commands with `git -C <path>` / `wt -C <path>` rather
92 than trusting the `cd` to persist.
93 - `Shell cwd was reset` → not reachable. Stop and ask the user to make it
94 reachable: add the repo, or a parent like `~/workspace`, to
95 `permissions.additionalDirectories` (durable, every session), or run
96 `/add-dir <path>` (this session). Then continue. Don't grind through
97 absolute paths with `cd` resetting on every command.
98 - **Denied** — the call itself was refused, with no tool error → however
99 the denial is worded, it is the user's answer to the confirmation Claude
100 Code shows for entering a worktree outside `.claude/worktrees/`, unless
101 there was no user to ask (the denial says the session couldn't prompt),
102 which decides nothing — take the recovery above. On the user's answer:
103 the worktree `wt` just created still exists; only the entry didn't
104 happen. Report its path and ask how to proceed, since reaching it
105 through `cd` would override that answer.
106
107## Cleanup
108
109The worktree is a normal worktrunk worktree: it shows up in `wt list` and is
110merged or removed with `wt merge` / `wt remove <branch>` like any other. Don't
111remove it unprompted.
112
113A worktree from step 2 that the session never touched — no changed files, no
114commits — is cleaned up when the session ends, branch included; anything
115written into it keeps it. A worktree from step 3 always stays. If the user asks
116to leave mid-session, `ExitWorktree({action: "keep"})` returns the session to
117its original directory;
118`ExitWorktree` cannot remove a worktree entered by `path`, so removing one of
119those is always `wt remove <branch>`.
120
121## Scope
122
123The command's mandate is ONE worktree (in the named repo, if one was given)
124and the requested task inside it. Commits, pushes, and merges still each
125require explicit user permission.