# Prp Worktree

> Git-native worktree management via a bundled single-file CLI - create, list (with per-worktree git stats), and safely tear down isolated checkouts under .worktrees/ for parallel workstreams. Use when the user or an orchestrating skill wants to "create a worktree", "work on this in a separate worktree", "spin up an isolated checkout", "list my worktrees", "clean up / remove a worktree", or invokes $prp-worktree.

- Skill: `wirasm/prp-worktree` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add wirasm/prp-worktree`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wirasm/prp-worktree/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Wirasm (https://skillmd.com/u/wirasm)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/wirasm/prp-worktree

---


> **Arguments:** `$ARGUMENTS` (and `$1`, `$2`, ...) refer to the arguments given when this skill was invoked. Take them from the user's request; if absent, infer them from the conversation.

# PRP Worktree

Manage isolated git worktrees for parallel workstreams with one bundled script — deterministic create/teardown with safety rails, instead of improvised `git worktree` incantations.

**Input**: $ARGUMENTS (if absent, infer the subcommand and worktree name from the conversation).

## Run it

All operations are one command (never re-implement them with raw git):

```bash
uv run .agents/skills/prp-worktree/scripts/worktree.py create <name> [--base <branch>]
uv run .agents/skills/prp-worktree/scripts/worktree.py list [--base <branch>] [--json]
uv run .agents/skills/prp-worktree/scripts/worktree.py remove <name> [--force] [--delete-branch]
```

- **create** — worktree at `.worktrees/<name>` on branch `<name>` (new from `--base`, or checked out if the branch already exists). Prints the absolute worktree path as its **final line** — `cd` there to start working.
- **list** — every managed worktree with branch, ahead/behind vs base, dirty file count, diffstat (`files +ins/-dels`), merged-into-base, and last-commit age. `--json` for machine consumption.
- **remove** — refuses if the worktree has uncommitted changes (`--force` discards). The branch is kept by default (with a pushed-to-origin report); `--delete-branch` deletes it only if merged into base (`--force` overrides). Never force without first investigating what would be lost.

## Conventions

- Worktrees live **inside the repo** at `.worktrees/<name>` — within sandbox-writable roots on any agent harness — and are auto-excluded from git via `.git/info/exclude`; they never appear in `git status`.
- Branch name = worktree name (slashes allowed in branch; directory name flattens `/` to `-`).
- Default `--base` is the repo's default branch (origin HEAD), falling back to the current branch.
- The script always operates on the **main checkout**, wherever it is run from — including from inside a worktree.

## Gotchas

- Requires `uv` and `git` on PATH; the script is stdlib-only (PEP 723, Python ≥ 3.10).
- `remove` deletes the checkout, not the work: commits live on the branch and survive; only `--force` on a dirty worktree discards uncommitted changes.
- Orchestrating skills compose this by name ("use the prp-worktree skill to create `<name>`") — one worktree per parallel agent prevents checkout collisions.

## Resources

- `scripts/worktree.py` — the CLI (run it, don't read it); `--help` on any subcommand for exact flags.