worktree-cleanup

worktree-cleanup

Prunes git worktrees created under <repo>/.claude/worktrees/ that are finished and safe to delete. Branch refs are always kept, so every removal is reversible.

The deterministic work lives in worktree-cleanup.sh. Do not reimplement the logic inline; call the script. It is the single source of truth so an unattended routine and an interactive run behave identically.

Guardrails (why this is safe to automate)

A worktree is removed only if all of these hold; otherwise it is kept:

1. Scope-locked — path is inside .../.claude/worktrees/. The primary working tree, and anything outside that dir, is never touched.
2. Not locked — git worktree's locked flag is respected.
3. Not active — no live process has its cwd at or under the worktree (lsof -d cwd). This is what stops you from deleting a worktree another Claude/editor/dev-server session is sitting in.
4. Idle — not touched in the last --min-idle-hours hours (default 72). "Touched" is the newest of: its top-level file mtimes, its per-worktree git activity (index/reflog/checkout/fetch), and its HEAD commit time. Catches "finished and clean, but someone was just in it." No full-tree walk, so node_modules neither slows it down nor falsely keeps it alive.
5. Clean — git status --porcelain is empty, untracked files included. Uncommitted work is the only truly unrecoverable loss, so a dirty tree is an automatic keep.
6. Done — no open PR, and either the latest merged PR's head equals the current branch tip (asked via gh, whose headRefOid is frozen at merge time, so this is exact even under squash-merge), or the branch has zero unique commits vs the default branch. A branch whose session continued after a merge — commits sitting past the last merged PR with no newer PR yet — is kept, because that's unreviewed in-progress work, not finished work.

Never --force. Never delete branches. If git worktree remove itself refuses (its own dirty/lock backstop), the worktree is kept and the refusal is logged.

Failure mode is conservative by design. If gh is unreachable or auth fails, a branch with commits falls through to "unmerged, kept" — a gh outage can only cause under-deletion, never data loss.

Recover a wrongly-removed worktree: git -C <repo> worktree add <path> <branch>.

Interactive use (default — a human is present)

1. Dry-run first. Output is a markdown table of EVERY worktree found, full paths: | Decision | Worktree | Reason |. Whole tree, or one repo:

   ${CLAUDE_SKILL_DIR}/worktree-cleanup.sh
   ${CLAUDE_SKILL_DIR}/worktree-cleanup.sh --repo ~/work/karta
   

   --dry-run is an explicit no-mutation alias producing the same table (it wins if combined with --remove). In --remove mode the Decision column reads REMOVED / REFUSED so the same table doubles as the action log.
2. Present the KEEP/REMOVE rows to the user and get a single batch sign-off per folder. Rows reading PR #N MERGED but K commit(s) added since are kept on purpose — that's a session continued after its merge; resolve those by opening the follow-up PR (or dropping the commits), not by deleting the worktree.
3. On approval, run the same scope with --remove:

   ${CLAUDE_SKILL_DIR}/worktree-cleanup.sh --repo ~/work/karta --remove
   

   --remove re-evaluates every guardrail fresh, so nothing that became dirty or active between preview and removal is touched.
4. Report the summary line (KEEP=… REMOVE=… removed=… refused=…).

Unattended use (scheduled)

Run with --remove directly; the table is the action log (Decision = REMOVED/REFUSED):

${CLAUDE_SKILL_DIR}/worktree-cleanup.sh --remove

Safe without sign-off: it only removes clean, inactive, idle, merged-or-empty worktrees, and keeps branch refs.

To run it on a schedule, create a LaunchAgent (the scheduled-jobs skill in this plugin does this for you). Two things matter for an unattended run:

• PATH must include your package manager's bin (e.g. /opt/homebrew/bin) — a launchd job's default PATH omits it, and a missing gh makes every merged branch look un-merged. (scheduled-jobs create bakes this in.)
• Run it as a LaunchAgent (user session), not a LaunchDaemon or bare cron, so the gh token in the macOS keychain is reachable. Outside a session pass GH_TOKEN. Either way the failure mode is conservative: no gh = under-deletion, never data loss.
• Schedule it for a time the machine is awake; launchd runs a missed time on wake.

macOS only (lsof, BSD date/stat).

Notes / known limits

• "Active" is detected via process cwd, not open file handles. A clean, merged worktree with only an editor file open (cwd elsewhere) can still be removed; that closes the file but loses nothing (tree is clean).
• Default branch is read from origin/HEAD, falling back to main/master.