cleanup

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 and the running processes decide which worktrees are in use, a worktree whose changes the project's checkout already holds counts as clean, Next.js cache folders join the list, and the block's Autopilot rule lets the safe set go without asking. scripts/scan.mjs beside this file makes every verdict, so a rerun reaches the same one. Its --landed <worktree> mode runs the same content check on one worktree, and a card session runs it before it deletes its own.

/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 session that is not archived claims it, it changed in the last day and no session claims it, or a server holds a cache inside it. The scan also keeps it when lsof cannot answer.
   • SAFE for a worktree: an archived session owned it, it sits where agents make worktrees, and every change in it is committed on a branch or already in the checkout. A changed file is in the checkout only when the checkout holds a file with the same spelling, case included, that matches it byte for byte. That file must not resolve back into the worktree, such as through a symlinked folder. An ignored file needs no copy when an install or build recreates it, such as node_modules, a .next folder, or a dist or build folder beside a package.json; any other ignored file needs such a copy, proof folders and test reports included. Agents make worktrees in the app's .claude/worktrees, a temp or scratch folder and the run directory.
   • ASK for a worktree: no session claims it, it sits outside those folders, another worktree lives inside it, it holds a submodule or nested repository, a staged version differs from its file, the checkout lacks one of its changes or ignored files, its commit is on no branch, or git still lists it after its folder was deleted.
   • 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, and lists the running processes once more 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 counts the hard links a package store shares once per folder. Then report what went and each row kept or asked, with its reason.

Run it once in each project checkout whose worktrees or caches the owner wants gone. A card session already removes its own worktree when its patch lands, as the chips Landing rule says, so the scan mostly finds worktrees from before that rule, proof worktrees a run left behind and dev caches.