v1.0.1 to v1.1.0

---

name: worktree-cleanup

description: >-

Clean up stale git worktrees to reclaim disk space. Detects merged branches,

deleted remotes, and abandoned worktrees. Rust-aware (reports target/ sizes

separately). Use for worktree cleanup or disk reclamation.

allowed-tools: AskUserQuestion, Bash, Read

model: sonnet

---

## Context

- Arguments: `${ARGS}`

- Main repo root: !`sh -c 'COMMON=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null) && dirname "$COMMON" || echo "NOT_IN_GIT_REPO"'`

- Default branch: !`sh -c 'ref=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed "s@^refs/remotes/origin/@@"); echo "${ref:-main}"'`

- Worktree count: !`git worktree list 2>/dev/null | wc -l | xargs`

- Platform: !`uname -s`

**Shell variables** do not persist across Bash tool calls. Re-derive from Context when needed.

# Worktree Cleanup

You analyze git worktrees in the current repo, classify them by safety tier, report disk usage, and interactively clean up stale worktrees. Especially useful for large Rust repos where each worktree has its own `target/` directory (often 1-15 GB).

## Argument Parsing

| Args | Behavior |

|------|----------|

| Empty | Analyze worktrees in the current repo |

| `--dry-run` | Report only, no removals |

If "Main repo root" is "NOT_IN_GIT_REPO" — stop and inform the user.

## Phase 0: Pre-flight

1. Validate the repo context from "Main repo root"

2. Parse `${ARGS}` for `--dry-run` flag

3. Fetch and prune remote tracking refs:

```bash

git fetch --prune origin 2>&1

```

## Phase 1: Discovery

List all worktrees using porcelain format for machine parsing:

```bash

git worktree list --porcelain

```

Parse each record (separated by blank lines) into: `worktree` (path), `HEAD` (sha), `branch` (ref), and optional `locked`/`prunable` flags. The first record is always the main worktree — skip it (it can never be removed).

Handle edge cases:

- `prunable` flag means the directory was already deleted — these need `git worktree prune`

- `detached` means detached HEAD — treat branch as the HEAD sha for display

- Corrupted worktrees (directory exists but git link is broken) are detected in Phase 2 check 3

## Phase 2: Analysis

For each non-main worktree, run the classification decision tree. Short-circuit on the first match — do not run expensive checks (merge-base, lsof) if an earlier check already classified the worktree.

### Classification Decision Tree

Run checks in this order:

```

1. Locked? (porcelain output shows "locked") → LOCKED

2. Directory missing? (porcelain shows "prunable") → PRUNABLE

3. Corrupted? (directory exists but git rev-parse --git-dir fails) → CORRUPTED

```

### Check Commands

Use `git --no-optional-locks -C <worktree-path>` for all checks to avoid lock contention with active processes. Always quote worktree paths in shell commands (e.g., `"<path>"`) to handle paths containing spaces.

**Check 3 — Corrupted:**

```bash

git --no-optional-locks -C <path> rev-parse --git-dir 2>/dev/null

```

Non-zero exit code when the directory exists on disk = corrupted worktree (`.git` file missing or broken link back to main repo). Report in the table as CORRUPTED and require individual approval for removal.

```bash

git --no-optional-locks -C <path> status --porcelain 2>/dev/null

```

Non-empty output = dirty (uncommitted changes, staged changes, or untracked files).

```bash

git --no-optional-locks -C <path> log @{upstream}..HEAD --oneline 2>/dev/null

```

Non-empty = unpushed commits → ACTIVE. If this command fails (no upstream set), try the fallback:

```bash

git --no-optional-locks -C <path> log origin/<default-branch>..HEAD --oneline 2>/dev/null

```

On macOS (Platform = "Darwin"):

```bash

lsof +d <path> 2>/dev/null | head -5

lsof +d <path>/.git 2>/dev/null | head -5

```

On Linux:

```bash

fuser <path> 2>/dev/null

```

Any output = directory in use. `+d` checks only the specified directory, not subdirectories — processes with files open deeper in the tree are not detected. This is a deliberate tradeoff: `+D` (recursive) is prohibitively slow on worktrees with large `target/` directories. The `.git` check catches git lock files held by active agent sessions. The `git worktree remove` safety check in Phase 4 (without `--force`) is the true safety net for dirty state.

Extract the branch name from the porcelain `branch` field (strip `refs/heads/` prefix). For detached HEAD worktrees, use the HEAD sha from porcelain output:

```bash

git merge-base --is-ancestor <branch-tip> origin/<default-branch>

```

Exit code 0 = merged.

```bash

git cherry origin/<default-branch> <branch-name> 2>/dev/null

```

```bash

git rev-parse --verify refs/remotes/origin/<branch-name> 2>/dev/null

```

Non-zero exit = remote branch no longer exists (was deleted after `git fetch --prune`).

```bash

git --no-optional-locks -C <path> log -1 --format=%ct 2>/dev/null

```

Compare the Unix timestamp to current time. Older than 30 days = stale.

### Disk Usage

For each worktree that has a directory on disk, measure size. Run these in a single Bash call to minimize round-trips:

```bash

du -sh <path> 2>/dev/null

du -sh <path>/target 2>/dev/null # Rust

du -sh <path>/node_modules 2>/dev/null # Node

du -sh <path>/build 2>/dev/null # Generic build dir

```

## Phase 3: Report

Present a structured report. Group worktrees by classification tier (SAFE first, then LIKELY_SAFE, PRUNABLE, STALE, ACTIVE, LOCKED).

### Report Format

```

## Worktree Cleanup Report

**Repo:** <main repo root>

**Worktrees:** <count> (excluding main)

**Default branch:** <default branch>

For PRUNABLE worktrees (directory already deleted), show N/A for Total and Build Artifacts columns.

### Summary

SAFE: N worktrees (X GB) — removable with confirmation

LIKELY_SAFE: N worktrees (X GB) — removable with confirmation

PRUNABLE: N worktrees (0 B) — metadata cleanup only

CORRUPTED: N worktrees (X GB) — require individual approval

STALE: N worktrees (X GB) — require individual approval

ACTIVE: N worktrees (X GB) — will not be removed

LOCKED: N worktrees (X GB) — will not be removed

Auto-reclaimable (SAFE + LIKELY_SAFE + PRUNABLE): X GB

Reclaimable with individual approval (STALE + CORRUPTED): X GB

```

If `--dry-run` is set, output the report and stop: "Dry run complete. No worktrees were removed."

## Phase 4: Cleanup

Skip entirely if `--dry-run` or if there are no SAFE/LIKELY_SAFE/PRUNABLE/STALE worktrees.

### Step 1: PRUNABLE worktrees

These have no directory on disk — only stale git metadata. Clean unconditionally:

```bash

git worktree prune -v

```

### Step 2: SAFE and LIKELY_SAFE batch

If there are SAFE or LIKELY_SAFE worktrees, present them as a batch using `AskUserQuestion`:

- Option 1: "Remove all N (X GB)"

- Option 2: "Select individually"

- Option 3: "Skip"

If "Select individually", present each one and let the user choose.

### Step 3: STALE and CORRUPTED worktrees

Present each STALE or CORRUPTED worktree individually using `AskUserQuestion`:

- "Remove `<branch>` (not merged, N days old, X GB)?" for STALE

- "Remove `<path>` (corrupted worktree, X GB)?" for CORRUPTED

- Option 1: "Remove"

- Option 2: "Skip"

### Step 4: Per-worktree removal

For each worktree approved for removal:

```bash

git branch -d <branch-name>

```

```bash

git branch -D <branch-name>

```

For LIKELY_SAFE, STALE, and CORRUPTED branches, also use `-D` (the remote is already gone or the user explicitly approved).

3. If branch deletion fails, report it but continue — the worktree removal is the important part.

### Step 5: Final cleanup and summary

Run a final prune to clean any remaining metadata:

```bash

git worktree prune -v

```

Present the final summary:

```

## Cleanup Complete

Worktrees removed: N

Branches deleted: N

Space reclaimed: ~X GB

Remaining worktrees: N

```

## Rules

1. **Never remove the main worktree** — skip it in all phases

3. **Never remove locked worktrees** — report them but do not offer removal

4. **Always show the report before any removal** — the user must see the full picture first

5. **Always confirm via AskUserQuestion** — no destructive actions without explicit user approval

6. **Use `git worktree remove`, never `rm -rf`** — ensures git metadata is cleaned atomically

8. **Batch parallel Bash calls** where possible — run multiple `du`, `git status`, `git log` checks in a single Bash invocation to minimize round-trips

## Abort & Recovery

If the user cancels mid-cleanup or an unexpected error occurs:

1. Run `git worktree prune -v` to clean any orphaned metadata

2. Report: how many worktrees were successfully removed, which removals were skipped, and that the repo is in a consistent state

3. The repo is always safe — `git worktree remove` (without `--force`) either completes atomically or fails without side effects

## Examples

- `/worktree-cleanup` — analyze and clean up worktrees in the current repo

- `/worktree-cleanup --dry-run` — report worktree status and disk usage without removing anything