worktree-hygiene

Audits and safely removes merged Git worktrees and branches across agent harnesses.

4.8k|376|Updated Mar 16, 2023
One-click install
npx skills add https://github.com/EpicenterHQ/epicenter --skill worktree-hygiene
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: worktree-hygiene
Source: https://github.com/EpicenterHQ/epicenter/tree/main/.agents/skills/worktree-hygiene
Command: npx skills add https://github.com/EpicenterHQ/epicenter --skill worktree-hygiene

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Git worktrees spawned by agent harnesses (warp, codex, opencode, conductor) accumulate with nothing reaping them, and deleting them blindly destroys uncommitted work. This Skill provides a safe, auditable procedure for deciding which worktrees and branches can be removed and which must be preserved.

Core Features & Use Cases

  • Containment-based audit: Classifies every worktree using git merge-base --is-ancestor against origin/main and git cherry to count unmerged commits, rather than trusting self-reported merge status.
  • Decision matrix for reaping: Distinguishes merged-and-clean worktrees, throwaway dirt (lockfile churn), real uncommitted work, detached-HEAD states, and stacked branches, with exact commands for each case.
  • Repo-specific safeguards: Covers shared-stash hazards, animal-named stacked warp branches, HEAD verification before committing, and the one-owner-per-worktree invariant.
  • Use Case: After several agent sessions, run a periodic sweep: audit all worktrees, present an approve-list of exact removal commands grouped by tier, reap the safe ones, anchor detached work into holding/* branches, and finish with git worktree prune.

Quick Start

Audit all Git worktrees in this repository and tell me which ones are safe to remove, then reap the approved ones.

Frequently Asked Questions about worktree-hygiene

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

FAQPage Schema
How do I safely remove merged Git worktrees?

First verify the branch is fully contained in origin/main with git merge-base --is-ancestor, then check the working tree with git status --porcelain. Only run git worktree remove and git branch -d when the branch is merged and the tree is clean or holds only throwaway dirt.

How to check if a Git branch is fully merged into main?

Use git merge-base --is-ancestor <branch> origin/main; if it succeeds, every commit on the branch is in origin/main. git cherry origin/main <branch> complements this by listing unmerged commits as + lines.

Why does git worktree remove fail with Directory not empty?

The removal fails when ignored files like node_modules or .DS_Store remain in the worktree directory. The worktree is still de-registered, so finish with git worktree prune followed by rm -rf on the leftover path.

When should I not delete a Git worktree?

Do not reap worktrees with real uncommitted work, unmerged commits, or detached HEADs holding unique edits. Anchor detached work first with git switch -c holding/<name>, and never reap a worktree owned by another live session.

Is git stash safe to use across multiple worktrees?

No, the stash is shared across all worktrees in a repository, so a bare git stash or stash pop can grab another worktree's entry. Prefer explicit branches over stash when working with multiple worktrees.