Gh Wt

gh-wt

gh wt creates CoW-backed git worktrees. Prefer it over git worktree add when the user wants multiple concurrent worktrees.

If gh wt is unavailable, run gh extension install HikaruEgashira/gh-wt and retry.

Commands

gh wt add  [path]   Create a worktree (creates or tracks )
gh wt list                  List worktrees
gh wt remove [target]       Remove a worktree; target = path or branch name
gh wt gc                    Delete unreferenced cache entries
gh wt --  [args...]    cd into selected worktree, then exec 
gh wt  [args...]       Run  with selected worktree path appended

When a subcommand needs a worktree and none is given, fzf opens for selection. Esc cancels cleanly (exit 0).

-- vs no --

• gh wt -- — cwd becomes the worktree, then `` runs.

Use for shells, agents, and test runners: gh wt -- claude, gh wt -- bash, gh wt -- npm test.

• gh wt — worktree path is appended as an argument.

Use for editors and openers that take a path: gh wt code, gh wt cursor.

Mnemonic: -- means "into"; no -- means "with path".

Typical requests → commands

| User says | Command | | --------------------------------------- | ----------------------------- | | "new worktree for `" | gh wt add | | "run claude / my agent in a worktree" | gh wt -- claude | | "open in VS Code / Cursor" | gh wt code / gh wt cursor | | "run tests in a separate worktree" | gh wt -- npm test | | "remove the worktree" | gh wt remove | | "show me all worktrees" | gh wt list | | "clean up unused worktree cache" | gh wt gc` |

Gotchas

• macOS cross-volume: the target path and the cache dir must be on

the same APFS volume, or clonefile(2) fails with apfs clone failed. Fix by setting GH_WT_CACHE_DIR=/path/on/same/volume before gh wt add.

• gh wt remove refuses the main worktree.

Source & license

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

• Author: HikaruEgashira
• Source: HikaruEgashira/gh-wt
• License: MIT

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