prp-worktree

Creates, lists, and removes git worktrees under .worktrees/ for parallel agent workstreams.

2.2k|608|Updated Jun 21, 2025

Search Tags:#agent workflow #Git #CLI #worktree #Parallel Development #Branch management

Ready to run

npx skills add https://github.com/Wirasm/PRPs-agentic-eng --skill prp-worktree

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: prp-worktree
Source: https://github.com/Wirasm/PRPs-agentic-eng/tree/main/plugins/prp-core/skills/prp-worktree
Command: npx skills add https://github.com/Wirasm/PRPs-agentic-eng --skill prp-worktree

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

Running multiple agents or workstreams against one repository causes checkout collisions and improvised git worktree commands with inconsistent safety checks. This Skill wraps worktree lifecycle management in a single deterministic CLI with guardrails against data loss.

Core Features & Use Cases

Deterministic create/remove: Creates worktrees at .worktrees/<name> on a matching branch, auto-excluded from git status, and refuses to remove worktrees with uncommitted changes unless forced.
Rich status listing: Shows per-worktree branch, ahead/behind counts, dirty file count, diffstat, merge status, and last-commit age, with a --json mode for machine consumption.
Safe branch cleanup: Deletes branches only when merged into the base branch, and reports whether a kept branch was pushed to origin.
Use Case: An orchestrating agent spins up three parallel workstreams by creating one worktree per agent, lists their progress with git stats, then tears each down safely once its branch is merged.

Quick Start

Ask the agent to use the prp-worktree skill to create a worktree named "feature-x" and then list all managed worktrees with their git stats.

Frequently Asked Questions about prp-worktree

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I create a git worktree for parallel development?▼

Run the bundled CLI with `create <name>` to make a worktree at .worktrees/<name> on a branch of the same name, based on the repo's default branch or a `--base` you specify. It prints the absolute path as its final line so you can cd there directly.

How do I list git worktrees with branch status?▼

Use the `list` subcommand to see every managed worktree with its branch, ahead/behind counts versus the base, dirty file count, diffstat, merge status, and last-commit age. Add `--json` for machine-readable output.

Can I remove a git worktree with uncommitted changes?▼

The remove command refuses to delete a worktree that has uncommitted changes, protecting your work by default. You must commit or stash the changes first, or explicitly pass `--force` to discard them.

Does git worktree remove delete the branch too?▼

No, the branch is kept by default and the tool reports whether it was pushed to origin. Passing `--delete-branch` deletes it only if it is merged into the base branch, unless `--force` overrides the check.

What are the requirements for running this worktree CLI?▼

The script requires git and uv on PATH and Python 3.10 or later, and it uses only the standard library via a PEP 723 script header. It must be run inside a git repository and always operates on the main checkout, even from inside a worktree.