engineering / Git & commits
worktree
Prefers the `wt` CLI (smeltery/worktree) over raw `git worktree` plumbing for creating, listing, opening, cleaning up, and removing worktrees.
Put it to work.
Ask your agent to use worktree, or let it load the skill when your task matches the description.
Use the worktree skillInvocation syntax varies by agent. Use the skill name in your prompt, or your agent’s supported slash command.
About this skill
Prefer the wt CLI over raw git worktree plumbing.
- Maps worktree create/list/open/cleanup/remove requests onto
wtcommands - Falls back to plain
git worktreewhenwtisn't installed - Respects
wt's hook-trust model instead of bypassing it
Install
npx skills@latest add smeltery/skillsOr copy just this skill:
mkdir -p ~/.claude/skills/worktree
curl -fsSL https://raw.githubusercontent.com/smeltery/skills/main/skills/engineering/worktree/SKILL.md \
-o ~/.claude/skills/worktree/SKILL.mdThe skill expects the wt binary from
smeltery/worktree. If it's
missing, the skill builds it from source with cargo build --release, or
falls back to plain git worktree commands.
Usage
Use whenever a worktree needs to be created, listed, opened, cleaned up, or
removed — including as part of other workflows like /workon.
Files
SKILL.md— canonical skill definition.
Read the full SKILL.md
Check availability first
command -v wt >/dev/null 2>&1 && wt --versionIf missing, install from source (no published binary releases yet):
git clone https://github.com/smeltery/worktree.git
cd worktree
cargo build --release
cp target/release/wt ~/.local/bin/wt # or any directory on PATHIf cargo/Rust isn't available and installing a toolchain isn't appropriate for
the task at hand, fall back to plain git worktree (see below) rather than
installing one unprompted.
Commands
wt feature/my-branch Create a worktree
wt c feature/my-branch Same, explicitly
wt o Interactively open a checkout
wt ls List checkouts
wt rm [branch|.] Remove a worktree and optionally its branch
wt cleanup / wt clean Safely remove stale worktrees
wt setup / wt s [branch] Rerun repository setup hooks
wt run / wt r <name> [args...] Run a repository-defined command
wt trust / wt t Trust the current .worktree directory
wt doctor / wt d Inspect the current setupwt rm . targets the linked worktree containing the current directory. The
primary checkout is never removable. wt cleanup only removes worktrees that
are clean, have an upstream, and are not ahead of it — run with --dry-run
first to preview.
Running non-interactively
Since the Bash tool's stdout is not a TTY, wt automatically renders TOON
output, returns structured errors with a machine-readable code:, and never
prompts — a command that would have asked something fails instead and names
the flag that makes it explicit. Don't set ONE_OUTPUT=human unless a human is
actually going to read the output.
Trust prompts
wt requires explicit trust before running any hook committed under
.worktree/ in a repository, and re-requires it whenever that directory
changes. In agent mode an untrusted hook is never executed and never prompted
for — the command fails and names wt trust. Read the hook scripts under
.worktree/ before running wt trust; don't trust blindly just to unblock a
failing command.
Without wt (fallback)
git worktree add ../<branch-name> -b <branch-name>
git worktree list
git worktree remove <path>Plain git worktree has no equivalent to wt's repository-defined setup
hooks or stale-worktree cleanup — after adding a worktree this way, run any
project setup steps (install deps, copy env files) manually.