# Worktree

> Create, remove, or prune git worktrees for issue/PR isolation. Use when the user asks for a worktree, wants an isolated workspace per issue, or wants completed worktrees cleaned up.

- Skill: `gopherguides/worktree` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add gopherguides/worktree`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gopherguides/worktree/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: gopherguides (https://skillmd.com/u/gopherguides)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gopherguides/worktree

---


# Worktree

## Plugin Resource Resolution

`<PLUGIN_ROOT>` is notation. Replace it with a concrete absolute plugin root before every resource read or command:

- **Codex:** Start from the directory containing the absolute selected `SKILL.md` path, then ascend two directories (`skills/<name>` -> plugin root).
- **Claude Code:** Bind it to the injected `${CLAUDE_PLUGIN_ROOT}` value.

Manage git worktrees for isolated per-issue/per-PR work. Three sub-actions, each in its own sibling file.

Before requesting decisions, read
`<PLUGIN_ROOT>/lib/driver-interaction.md` and follow its
cross-platform capability-binding rules.

Read `<PLUGIN_ROOT>/lib/decision-gates.md` before resolving action,
target, consent, or cleanup choices.

## Action selection

| User intent | Sibling | Slash command |
|---|---|---|
| Create one worktree for an issue or PR | `create.md` | `/create-worktree <num>` |
| Remove a specific worktree (interactively) | `remove.md` | `/remove-worktree` |
| Batch-clean all completed worktrees | `prune.md` | `/prune-worktree` |

Match the user's request to one of the three rows, then read the corresponding sibling for the full procedure.

If the request does not identify one action, follow the shared
**missing-intent gate**. Request create, remove, or prune intent and stop before
mutating worktrees.

## Conventions (apply to all three actions)

- **Worktree path**: `../<reponame>-issue-<num>-<title-slug>/` — sibling to the source repo, never inside it
- **Branch name**: `issue-<num>-<title-slug>`
- **Title slug**: lowercase, alnum + hyphens, derived from `gh issue view --json title`
- **Identifier rule**: `issue-<NUM>-` prefix is the trusted issue marker on a branch — `fix/2fa-login` contains a number but is NOT an issue branch
- **Default branch**: `git remote show origin | grep 'HEAD branch'` (handles repos with `main` vs `master` vs custom)
- **State file**: `<PLUGIN_ROOT>/scripts/worktree-state.sh` registers the active worktree so the pre-tool-use hook blocks accidental edits to the source repo

## Prerequisites (all three)

- `gh` CLI installed and authenticated
- Run from inside a git repository (any worktree of the repo, not just the main checkout)

## Further Reading

- `create.md` — full create procedure (PR vs issue detection, env-file copy, state registration)
- `remove.md` — interactive selection + safety-check matrix (issue closed? branch merged? uncommitted changes?)
- `prune.md` — batch evaluation, classification, confirmation, removal