Wt

Worktree Command

wt is the single entry point for worktree work. One command on both multiplexers. An earlier split had separate tmux and herdr commands; the only thing that differed was which surface showed the checkout.

The model

Git plumbing belongs to wt. The multiplexer is only a surface that wt renders a checkout onto.

• Checkouts always land at $WT_ROOT//, default ~/_wt.

Branch slugs are lowercased with / and spaces turned into -.

• That is the same layout herdr uses natively when

~/.config/herdr/config.toml sets [worktrees] directory = "~/_wt". A worktree made by wt new or by herdr's own prefix+shift+g is indistinguishable afterwards. One find lists them all, and wt remove can clean up any of them.

• Surface detection: HERDR_ENV=1 means herdr, otherwise $TMUX means tmux,

otherwise no surface (path is still created and copied). Both are inherited by agents launched from a pane. Force one with WT_SURFACE=herdr|tmux|none.

Never call herdr worktree create to make a worktree for the user. It hardcodes herdr's own naming decisions. wt new creates the checkout and then asks herdr to adopt it with herdr worktree open --path, which is why the same command works for a brand new branch and for re-opening something that already exists on disk.

Usage

Prefer the focused skills when intent is clear:

• wt-create - create a worktree, open it, carry changes, symlink envs, install deps
• wt-remove - remove a worktree, its branch, and its window/workspace
• wt-clear - one-off sweep closing windows whose PR is finished
• wt-cleanup-loop - the same sweep on a timer

Otherwise pass arguments straight through:

wt $ARGUMENTS

With no arguments wt opens an fzf picker, which is only useful for the human. As an agent, pick the subcommand yourself.

wt new  [-c|--clean] [-b|--branch ]
wt open 
wt remove [branch|slug|path] [--force]
wt clear [--merged-only]
wt cleanup-loop [tick] [duration]      # defaults 5m 3h
wt list

Herdr details

• A new worktree workspace is one pane, nothing else. Split it yourself when

the work needs a shell or a dev server. herdr pane split returns the new pane_id in .result.pane.pane_id, so there is no diffing of pane lists.

• herdr hangs a worktree workspace off a source workspace. wt new names its

own workspace (--workspace, resolved from HERDR_PANE_ID), so the subtree appears where you invoked it. Identifying the repo by path instead (--cwd ) lets herdr choose: the first workspace holding that repo key, or a new one it invents. That is only what you want when the invoking pane is itself inside a linked worktree and cannot be a source.

Implementation

All behaviour lives in scripts/ at the repo root. ./install.sh puts that directory on PATH and fpath. If wt: command not found comes back, that install is what to check first.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: OndrejDrapalik
• Source: OndrejDrapalik/worktree-management-skills
• License: MIT

Install and usage instructions live in the source repository linked above.