Worktree Sweep

Find and remove stale git worktrees, then report reclaimed space.

Operates in report → confirm → execute order. Nothing is removed until the user approves the plan. After approval, perform the removals autonomously. Choices are gathered through interactive questions, not flags.

Step 0: Determine the scan scope (never hardcode paths)

Resolve where to look, in this priority order:

1. A path passed in $ARGUMENTS — use it verbatim as the scan root.
2. Otherwise, if the current working directory is inside a git repository, ask the user (interactive question) which scope to use:

• this repository only — the repo the current directory belongs to;
• all repositories under the clone root — find the hosting root by walking up to the common ancestor that contains many / directories, and show the resolved root in the question so the user can confirm or correct it.

1. If the current directory is not inside a repository and no path was given — ask the user for the directory to scan. Do not assume a default like ~/git.

For multi-repo scope, enumerate repositories by locating each .git directory (a directory, not a gitdir file) under the resolved root.

Step 1: Enumerate worktrees

For each in-scope repository:

git -C "$REPO" worktree list --porcelain

The first entry is the main checkout — never a removal candidate. Every additional entry is a candidate. Also note the current worktree (the one this session runs in, if any) and exclude it.

Step 2: Classify each candidate

For every candidate worktree path $WT:

• Dirty — uncommitted or untracked changes:

``bash git -C "$WT" status --porcelain ``

A non-empty result means dirty. Inspect what changed before judging (see Step 4).

• Locked — git worktree list --porcelain prints a locked line. Read the lock reason. If it embeds a PID (e.g. pid 29180), check whether that process is still alive:

``bash ps -p "$PID" >/dev/null 2>&1 && echo live || echo stale ``

A stale lock (dead PID) is safe to clear. A live lock means a process is actively using the worktree — never remove it.

• Prunable — the entry carries a prunable line. The gitdir file points to non-existent location reason (the working directory is gone) is reported immediately by plain git worktree list --porcelain; purely age-based prunability is instead gated by gc.worktreePruneExpire (default 3 months) unless --expire is passed. Either way, git worktree prune (Step 5) is the authoritative cleanup.

• Clean — none of the above. Safe to remove.

Measure reclaimable size per candidate with du -sk "$WT" and total it.

Step 3: Report and ask

Present a table: repository, worktree path, branch (or detached HEAD), classification, size. Sum the reclaimable total for the clean + stale-locked set. Call out separately:

• worktrees in detached HEAD with commits not reachable from any branch (removal orphans those commits — recoverable only via reflog until gc),
• dirty worktrees (held back pending Step 4),
• live-locked worktrees (skipped).

Then ask the user (interactive question) which set to remove — e.g. the safe set (clean + stale-locked), or a narrower selection. Nothing is removed without that approval.

Step 4: Triage dirty worktrees

Do not blanket-remove dirty worktrees. Show the diff/stat and decide per item:

• Trivial drift — regenerated lockfiles (package-lock.json, go.sum), generated code (zz_generated.*), editor cruft, stray binaries not in git. Safe to discard with approval.
• Real work — hand-written source changes, an uncommitted refactor. Ask the user whether to keep the worktree, commit/stash the change first, or discard it. Never silently discard real work.

Step 5: Execute (after approval)

For each approved worktree:

1. Stale lock → clear it first: git -C "$REPO" worktree unlock "$WT".
2. Restore the write bit before removing. Build/module caches inside a worktree are often read-only directories. A plain remove can deregister the worktree from git's metadata and then fail mid-delete on the read-only directory, leaving an orphaned tree that git no longer tracks. Pre-empt it:

``bash chmod -R u+w "$WT" git -C "$REPO" worktree remove --force "$WT" ``

1. After processing a repo: git -C "$REPO" worktree prune to clear prunable and any stale admin refs.

If a worktree was already deregistered but its directory remains on disk (orphaned), remove the directory tree directly — git worktree remove no longer applies to it.

Step 6: Report reclaimed space

Re-measure and report total space freed, the count removed, and anything intentionally kept (dirty-real-work, live-locked) with the reason.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: lexfrei
• Source: lexfrei/ccc
• License: BSD-3-Clause

Install and usage instructions live in the source repository linked above.