OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add max-sixty/worktrunk --skill wt-switch-create
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.
npx skills add max-sixty/worktrunk --skill wt-switch-create
Arguments: $ARGUMENTS. Grammar: [<branch>] [<repo>] [-- <task>].
Tokens before the -- are the branch and/or repo. A path-shaped token
(starting with /, ~, ./, or ../) is the repo. A bare name can be
either, so make an informed guess. It is the branch when the current repo
already has a branch by that name, as it is for wt switch itself. Otherwise
it is the repo when a git repository by that name exists where the user keeps
repos (beside the current repo, or in a workspace directory like
~/workspace), and the branch when none does (docs is a branch, not the
current repo's docs/ directory). A name read as the repo carries its absolute
path forward: that path, not the bare token, is the <repo> in step 3. Two
tokens that both read as branches don'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 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).
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):
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.
With a repo argument, cd <repo> next, in its own Bash call.
EnterWorktree re-roots only within the repository the cwd is in, and
worktrunk's PermissionRequest hook answers the confirmation that call
asks for only for a wt worktree of that same repository. If the cd
reports Shell cwd was reset, the repo is unreachable: skip the entry and
hand back as in Unreachable below.
Then call EnterWorktree({path: "<path from the JSON>"}).
Cannot enter worktree: …) → graceful; nothing moved, and one recovery covers them
all. The common cause is a session already rooted in a worktree (or 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:
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 → Unreachable. Stop and ask the user to make
the directory whose cd reset reachable: add a parent that holds both
the repo and its worktrees, like ~/workspace, to
permissions.additionalDirectories (durable, every session), or run
/add-dir on it (this session). Then continue from that cd. Don't
grind through absolute paths with cd resetting on every command..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. cd back out of the repo you moved into, if any, then report
the worktree's path and ask how to proceed, since reaching it through
cd would override that answer.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>.
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.