/cleanup

name: cleanup
description: "Free disk in a project by removing the git worktrees and Next.js cache folders nothing uses, keeping every worktree a session or process works in and every cache a running server holds. Use for /cleanup, \"clean up worktrees\", \"free disk space\", \"what's using my disk\", \"delete unused worktrees or builds\", or when a session-start hint counts old cleanup candidates."
argument-hint: '[scan]'

Cleanup

pstack's Worktree and simulator cleanup playbook is the method, and this skill wins where the two differ. When you remove a worktree yourself, use only `git worktree remove --force`, never `rm -rf` or `git worktree prune`. This skill adds what it lacks for this setup: the runtime's session list, session transcripts and running processes decide which worktrees are in use, uncommitted changes never keep a worktree, Next.js cache folders join the list, and the block's Autopilot rule lets the safe set go without asking. A card session lands its uncommitted changes in the checkout as a patch, so a leftover worktree's changes are usually there already, even when the checkout has edited them since. `scripts/scan.mjs` beside this file makes every verdict, so a rerun reaches the same one. Its `--landed <worktree>` mode checks that the checkout holds every change and ignored file of one worktree. Each file must match byte for byte, except a tracked file another landed patch also edited, whose hunks the checkout's copy must hold. A card session runs it right after its patch lands, before it deletes its own. Its `--remove <worktree>...` mode judges nothing. The chips sweep passes it the worktrees of the landed card sessions it archived, and the mode stops each process working in one, saves the uncommitted changes the checkout lacks as a patch, saves each commit no branch, tag or remote reaches as a second patch, and removes it. It keeps a worktree git does not list, a locked one, one outside the folders agents make worktrees in, one holding another worktree, the one it runs in, one whose commits git cannot list, one whose processes `lsof` cannot list and one git refuses to remove. The scan and `--landed` hold back a worktree with such a commit, which only its HEAD history keeps once a switch or reset leaves it, because the removal deletes that history. `--remove` saves it instead, because a card session commits its work in its own worktree and lands the same change here as a patch.

`/cleanup scan` lists and removes nothing. `/cleanup` removes the safe set.

1. Record `df -h /`. 2. List every session, archived ones included, with the runtime's session tool, such as Claude Code desktop's `list_sessions` with `include_archived` and a `limit` above the session count. Save its JSON array to the run directory. Without a session list no worktree can be safe, so a runtime with no session tool removes only caches. 3. From the project's checkout, run `node <this skill>/scripts/scan.mjs --repo . --sessions <that file>` in the background, because it measures every folder with `du`. It prints one row per worktree and cache folder, `SAFE`, `ASK` or `KEEP` with its size and reason, and the count and size of each.

• `KEEP` for a worktree: git lists it as locked, the scan runs in it, a running process such as a session, shell or dev server works in it, a running session, or one the owner pinned, claims it, or a server holds a cache inside it. A worktree no session claims stays while the session whose scratch folder holds it wrote its transcript in the last day, or, outside a scratch folder, while it changed in the last day. The scan also keeps it when `lsof` cannot answer.
• `SAFE` for a worktree: it sits where agents make worktrees and nothing above keeps it. No session that claims it is running, or none claims it and it has been quiet for a day. A session left open but idle does not keep it. Its uncommitted changes do not keep it. `--delete` saves the ones the checkout lacks as a patch under the repository's git folder, in `cleanup/`, before it removes the worktree, and its branch stays. A worktree whose every change the checkout already holds gets no patch, because its card's landing patch is the record. A worktree whose folder is already gone is also `SAFE`, because only git's record of it goes. Agents make worktrees in the app's `.claude/worktrees`, a temp or scratch folder and the run directory.
• `ASK` for a worktree: it sits outside those folders, another worktree lives inside it, or it holds a submodule or nested repository with changes.
• `KEEP` for a cache: a running server holds its `dev/lock` or `lock`, it is a build output (`.next` or `.next-plite`), or something wrote it in the last hour. A production build, which holds `BUILD_ID`, and a port's dev cache (`.next-<port>`) also stay for a week after their last use. Otherwise it is `SAFE`. A cache inside a safe worktree goes with that worktree.

4. For `/cleanup scan`, report the table and stop. Otherwise save the session list again as step 2 does, then run the same command with `--delete` and the new file. It measures each safe item, judges it again, lists the running processes once more and saves a worktree's uncommitted changes the checkout lacks as a patch right before removing it, so a folder stays when a process started working in it, or a server took it, during the scan. A desktop session reopened with no process in the folder yet is the one case it cannot see. It removes a worktree with `git worktree remove --force`, and a failed removal turns that row into `ASK`. Never run `git worktree prune` or `git stash`. 5. List each `ASK` row for the owner with its path, size, reason and session title. Remove only the ones the owner names, with `git worktree remove --force <path>`. Lock each one the owner keeps with `git worktree lock --reason "<why>" <path>`, so later scans and the session-start hint skip it. 6. Record `df -h /` again and report the space freed from the two `df` readings, because `du` cou