# Gh Wt

> Use this skill whenever the user wants to operate on git worktrees — create, enter, list, remove, or garbage-collect — including parallel agent sessions, side-by-side PR reviews, benchmarking multiple branches, or isolating a dirty tree from a fresh checkout. Trigger even when "worktree" is not said — phrasings like "spin up a fresh copy of branch X", "run claude in a clean checkout", "try this patch without touching my changes", or "open PR-123 side-by-side with main" all qualify. Do NOT trigger for conceptual or educational questions about git worktree (e.g. "what's the difference between git worktree and git clone?") — those are answered from general git knowledge, not this skill.

- Skill: `hikaruegashira/gh-wt` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add hikaruegashira/gh-wt`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hikaruegashira/gh-wt/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: HikaruEgashira (https://skillmd.com/u/hikaruegashira)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hikaruegashira/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 <branch> [path]   Create a worktree (creates or tracks <branch>)
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 -- <cmd> [args...]    cd into selected worktree, then exec <cmd>
gh wt <cmd> [args...]       Run <cmd> 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 -- <cmd>`** — cwd becomes the worktree, then `<cmd>` runs.
  Use for shells, agents, and test runners: `gh wt -- claude`,
  `gh wt -- bash`, `gh wt -- npm test`.
- **`gh wt <cmd>`** — 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 `<branch>`"           | `gh wt add <branch>`          |
| "run claude / my agent in a worktree"   | `gh wt -- claude`             |
| "open `<worktree>` in VS Code / Cursor" | `gh wt code` / `gh wt cursor` |
| "run tests in a separate worktree"      | `gh wt -- npm test`           |
| "remove the `<branch>` worktree"        | `gh wt remove <branch>`       |
| "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.