aidenlx/zotlit / .agents/skills/worktrunk
worktrunk
VerifiedGuidance for Worktrunk (the `wt` CLI) — git worktree management, hooks, and config. Load when working out which worktree a `wt` command will act on, or reaching for the global `-C <path>` to target one; editing .config/wt.toml or ~/.config/worktrunk/config.toml; adding, modifying, or debugging hooks (post-merge, post-start, pre-commit, pre-merge, post-switch, etc.); configuring commit message generation or command aliases; or troubleshooting wt behavior. Also answers general worktrunk/wt questions.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.2 KB |
| reference/claude-code.md | markdown | 7.0 KB |
| reference/code-signing.md | markdown | 4.9 KB |
| reference/config.md | markdown | 49.9 KB |
| reference/extending.md | markdown | 12.0 KB |
| reference/faq.md | markdown | 20.4 KB |
| reference/hook.md | markdown | 20.4 KB |
| reference/list.md | markdown | 30.6 KB |
| reference/llm-commits.md | markdown | 8.2 KB |
| reference/merge.md | markdown | 7.0 KB |
| reference/remove.md | markdown | 7.4 KB |
| reference/shell-integration.md | markdown | 8.3 KB |
| reference/step.md | markdown | 30.8 KB |
| reference/switch.md | markdown | 13.3 KB |
| reference/tips-patterns.md | markdown | 20.5 KB |
| reference/troubleshooting.md | markdown | 6.4 KB |
| reference/worktrunk.md | markdown | 8.1 KB |
reference/switch.md
View on GitHub# wt switch
Switch to a worktree; create if needed.
Worktrees are addressed by branch name; paths are computed from a configurable template. Unlike `git switch`, this navigates between worktrees rather than changing branches in place.
## Examples
```console
$ wt switch feature-auth # Switch to worktree
$ wt switch - # Previous worktree (like cd -)
$ wt switch --create new-feature # Create new branch and worktree
$ wt switch --create hotfix --base production
$ wt switch pr:123 # Switch to PR #123's branch
$ wt switch https://github.com/owner/repo/pull/123 # ...or paste the PR's URL
```
## Creating a branch
The `--create` flag creates a new branch from `--base` — the default branch unless specified. Without `--create`, the branch must already exist. Switching to a remote branch (e.g., `wt switch feature` when only `origin/feature` exists) creates a local tracking branch.
A new branch tracks the remote branch it starts from only when the two share a name: `--create release --base origin/release` tracks `origin/release`, while `--create feature --base origin/release` gets no upstream. Publish such a branch with `git push --set-upstream origin <branch>`, or set git's `push.autoSetupRemote = true` once.
## Creating worktrees
If the branch already has a worktree, `wt switch` changes directories to it. Otherwise, it creates one:
1. Runs [pre-switch hooks](https://worktrunk.dev/hook/#hook-types), blocking until complete
2. Creates worktree at configured path (or at `--path`)
3. Switches to new directory
4. Runs [pre-start hooks](https://worktrunk.dev/hook/#hook-types), blocking until complete
5. Spawns [post-start](https://worktrunk.dev/hook/#hook-types) and [post-switch hooks](https://worktrunk.dev/hook/#hook-types) in the background
```console
$ wt switch feature # Existing branch → creates worktree
$ wt switch --create feature # New branch and worktree
$ wt switch --create fix --base release # New branch from release
$ wt switch --create temp --no-hooks # Skip hooks
```
### Custom path [experimental]
`--path` places one worktree outside the `worktree-path` template, keeping the branch name intact:
```console
$ wt switch --create feature/JIRA-1234 --path ../dark-mode
$ wt switch ../dark-mode # Switch by path...
$ wt switch feature/JIRA-1234 # ...or by branch
```
Worktrunk finds the worktree from git's own records, so commands reach it by branch or path as usual. [`wt list`](https://worktrunk.dev/list/#worktree) marks it `⚐`, since it isn't at the path its branch implies, and [`wt step relocate`](https://worktrunk.dev/step/#wt-step-relocate) offers to move it back to the template path.
## Naming a worktree
Worktrees are addressed by branch name, and every argument that takes one also accepts the path of the worktree itself — resolved after the branch, so a directory never shadows a branch sharing its name. A path names what a branch cannot: a detached worktree, or one of two checkouts of the same branch. Relative paths resolve against `-C` and a leading `~` against the home directory, so a path worktrunk printed can be pasted back.
## Shortcuts
| Shortcut | Meaning |
|----------|---------|
| `^` | Default branch (`main`/`master`) |
| `@` | Current branch/worktree |
| `-` | Previous worktree (like `cd -`) |
| `pr:{N}` | GitHub PR #N's branch |
| `mr:{N}` | GitLab MR !N's branch |
```console
$ wt switch - # Back to previous
$ wt switch ^ # Default branch worktree
$ wt switch --create fix --base=@ # Branch from current HEAD
$ wt switch --create fix --base=pr:123 # Branch from PR #123's head
$ wt switch pr:123 # PR #123's branch
$ wt switch mr:101 # MR !101's branch
```
Shortcuts also apply to `--base`.
## Interactive picker
When called without arguments, `wt switch` opens an interactive picker to browse and select worktrees with live preview. The candidate set widens with `--branches` (local branches without worktrees), `--remotes` (remote branches), and `--prs` (open PRs/MRs — see below).
The CI column shows each row's PR/MR CI and review status, the same as [`wt list --full`](https://worktrunk.dev/list/).
**Keybindings:**
| Key | Action |
|-----|--------|
| `↑`/`↓` | Navigate worktree list |
| (type) | Filter worktrees |
| `Enter` | Switch to selected worktree |
| `Alt-c` | Create new worktree named as entered text |
| `Alt-x` | Remove selected worktree/branch (never forces; not the current worktree) |
| `Alt-y` | Copy selected branch name to the clipboard |
| `Alt-o` | Open the selected row's PR/MR URL in the browser |
| `Alt-r` | Refresh the list (pick up worktrees created elsewhere) |
| `Esc` | Cancel |
| `Alt-1`–`Alt-8` | Jump to a preview tab |
| `Tab`/`Shift-Tab` | Cycle available preview tabs forward/backward |
| `Alt-p` | Toggle preview panel |
| `Ctrl-u`/`Ctrl-d` | Scroll preview up/down |
The filter matches each row's branch, path, and — when it has a PR/MR — the PR/MR's number, title, and author. Typing `+` narrows to linked worktrees, and `@` to the current worktree.
**Preview tabs:**
1. **diff** — One net diff from the comparison base through the current worktree: committed, staged, unstaged, and untracked changes
2. **working** — Staged, unstaged, and untracked changes against `HEAD`
3. **committed** — Committed changes since the comparison base
4. **log** — Recent commits; commits already on the default branch have dimmed hashes
5. **remote⇅** — Ahead/behind diff vs upstream tracking branch
6. **summary** — LLM-generated branch summary; requires `[list] summary = true` and [`commit.generation`](https://worktrunk.dev/config/#commit)
7. **pr** — The selected row's PR/MR, for any row whose branch has one
8. **comments** — The PR/MR's comment thread, fetched from the forge for any row whose branch has one
The comparison base is the merge-base with the default branch, or with its upstream when the local default branch lags. The picker opens on **diff** for local rows and **pr** for a PR/MR listed by `--prs` but not available locally. A tab with no content for the selected row has a dimmed label, and the active tab's label is underlined. `Tab` and `Shift-Tab` skip the dimmed tabs; `Alt-1` through `Alt-8` open any tab directly. After you choose a tab, that choice stays active while you navigate.
**Pager configuration:** The preview panel pipes diff output through git's pager. Override in user config:
```toml
# ~/.config/worktrunk/config.toml
[switch.picker]
pager = "delta --paging=never --width=$COLUMNS"
```
**Starting list-only:** Set `preview = false` under `[switch.picker]` to open the picker with the preview hidden; `Alt-p` still shows it.
## Pull requests and merge requests
The `pr:<number>` / `mr:<number>` shortcut and the PR/MR's web URL both resolve to its branch. For same-repo PRs/MRs, worktrunk switches to the branch directly. For fork PRs/MRs, it fetches the ref (`refs/pull/N/head` or `refs/merge-requests/N/head`) and configures `pushRemote` to the fork URL.
```console
$ wt switch pr:101 # GitHub PR #101
$ wt switch https://github.com/owner/repo/pull/101 # ...the same PR, by URL
$ wt switch mr:101 # GitLab MR !101
$ wt switch https://gitlab.com/owner/repo/-/merge_requests/101 # ...the same MR, by URL
$ wt switch --prs # Browse open PRs/MRs in the picker
```
Both work anywhere a branch is accepted, including `--base`. The `--create` flag cannot be used with a PR/MR reference since the branch already exists.
If the PR or MR is on a fork, the local branch uses its branch name directly, so `git push` works normally. A pre-existing local branch with that name tracking something else requires renaming first.
The `--prs` flag adds the repository's open PRs (GitHub) or MRs (GitLab) that aren't already in the interactive picker. Selecting one switches to it as `pr:<number>` / `mr:<number>` would.
Requires `gh` (GitHub), `glab` (GitLab), or an equivalent CLI installed and authenticated; see [forge platform](https://worktrunk.dev/config/#forge-platform) for Gitea, Azure DevOps, and other supported platforms.
## When wt switch fails
- **Branch doesn't exist** — Use `--create`, or check `wt list --branches`
- **Path occupied** — Another worktree is at the target path; switch to it or remove it
- **Stale directory** — Use `--clobber` to remove a non-worktree directory at the target path
To change which branch a worktree is on, use `git switch` inside that worktree.
## Command reference
```
wt switch - Switch to a worktree; create if needed
Usage: wt switch [OPTIONS] [BRANCH] [-- <EXECUTE_ARGS>...]
Arguments:
[BRANCH]
Branch, worktree path, shortcut, or PR/MR URL
Opens interactive picker if omitted. Shortcuts: ^ (default branch), - (previous), @
(current), pr:{N} (GitHub PR), mr:{N} (GitLab MR)
[EXECUTE_ARGS]...
Additional arguments for --execute command (after --)
Each argument is expanded for templates and passed directly to the program.
Options:
-c, --create
Create a new branch
-b, --base <BASE>
Base branch
Defaults to default branch. Supports the same shortcuts as the branch argument: ^, @, -,
pr:{N}, mr:{N}.
--path <PATH>
Worktree directory for a new worktree [experimental]
Overrides the worktree-path template for this worktree. Relative paths resolve from the
current directory, as with git worktree add. The branch keeps its own name; afterwards,
switch by branch or by path.
-x, --execute <EXECUTE>
Program to run after switch
Runs one external program after switching, with full terminal control. Arguments after --
go directly to that program without Worktrunk shell parsing. Program lookup and argument
decoding follow the operating system. Shell syntax requires an explicit shell, for example
-x sh -- -c 'npm install && npm test'. On Windows, shell shims need their extension (-x
code.cmd) or an explicit shell such as -x cmd.exe -- /C code.
Without a branch argument, the interactive picker opens and the command runs against the
selected worktree — so wt switch -x claude picks a worktree, then launches Claude Code
there.
The program starts in the worktree the switch selected, whether or not your shell follows
it there: --no-cd governs only the shell.
Supports hook template variables ({{ branch }}, {{ worktree_path }}, etc.) and filters. {{
base }} and {{ base_worktree_path }} describe the source: the selected base with --create,
or the invoking worktree when switching to an existing worktree.
A variable inside a shell body is substituted before that shell parses it, so a path with
spaces splits into several arguments. Pass it as a separate argument instead — sh binds
the first one to $0, so the path arrives as $1:
wt switch feature -x sh -- -c 'cd "$1" && npm test' sh '{{ worktree_path }}'
Especially useful with shell aliases:
alias wsc='wt switch --create -x claude'
wsc feature-branch -- 'Fix GH #322'
Then wsc feature-branch creates the worktree and launches Claude Code. Arguments after --
are passed to the command, so wsc feature -- 'Fix GH #322' runs claude 'Fix GH #322',
starting Claude with a prompt.
Template example: -x code -- '{{ worktree_path }}' opens VS Code at the worktree, -x tmux
-- new -s '{{ branch | sanitize }}' starts a tmux session named after the branch.
--clobber
Remove stale paths at target
--no-cd
Skip directory change after switching
Hooks still run normally, and an --execute program still starts in the worktree — only
your shell stays put, so wt switch feature --no-cd -x code -- . opens the worktree in an
editor and leaves your terminal where it was. Useful when hooks handle navigation (e.g.,
tmux workflows) or for CI/automation. Use --cd to override.
-h, --help
Print help (see a summary with '-h')
Picker Options:
--branches
Include branches without worktrees
--remotes
Include remote branches
--prs
Include open PRs/MRs
Automation:
--no-hooks
Skip hooks
--format <FORMAT>
Output format
JSON prints structured result to stdout. Designed for tool integration (e.g., Claude Code
WorktreeCreate hooks).
[default: text]
[possible values: text, json]
Global Options:
-C <path>
Working directory for this command
--config <path>
User config file path
--config-set <toml>
Override config with inline TOML, e.g. --config-set list.full=true (repeatable)
-v, --verbose...
Verbose output (-v: info logs + hook/alias template variables on stderr; -vv: also debug
logs and raw subprocess output written to .git/wt/logs/). Set WORKTRUNK_VERBOSE=0|1|2 to
apply the same level everywhere — including shell completion, which no flag can reach
-y, --yes
Skip approval prompts
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |