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. In a pstack project, whose .agents/pstack.json names its plans directory, it counts only ignored files under <plans>/artifacts/, where a file counts once the checkout has its path, and skips commits only HEAD's reflog reaches, because there every other ignored file is build output or a copy and a landed squash leaves its originals in the reflog. 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 and then leaves its worktree for the scan. 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. They hold it back only while the commit writes a file whose content neither the checkout's HEAD nor its upstream has and neither changed since, so the commits a squash landing leaves behind do not, and --delete saves them as a patch before it removes the worktree. --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. /cleanup all removes it in every checkout beside this one, such as each repository in ~/git. Its steps 3 and 4 pass --repos <that folder> instead of --repo ., and the scan judges each checkout there that has linked worktrees against one session list. Schedule /cleanup all to run each day. One busy repository gained about ten subagent worktrees a day. du puts each at 2 GB or more, but on APFS a pnpm install clones the package store's files, so the space a worktree alone uses is mostly its builds and dev caches, 0.2 to 8 GB.
A project's session-start hook can run scan.mjs --brief --auto. Besides the hint line, it starts --delete in the background at most once a day per clone, from the session's own worktree, which that run keeps. It passes no session list, so only a running process, a lock, a server or the day's writes keep a worktree, and it removes only the SAFE set, while the ASK rows wait for /cleanup. Each start rewrites cleanup/last-run in the repository's git folder, which then holds the run's report. A user turns the run off with the line auto cleanup: off in ~/.claude/pstack-models.md, and git worktree lock --reason "<why>" <path> keeps one worktree.
- Record
df -h <checkout>. On macOS, df -h / reports the read-only system volume, not the data volume that holds the checkout.
- 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, a worktree that an idle session left open goes after a quiet day, as in the session-start run below.
- 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 also stays for a day after its last change or after the last write to a transcript of a session working in it, or of the session whose scratch folder holds it, unless every session that claims it is archived. Claude Code keeps the first kind of transcript in a folder of its projects folder named for the worktree path, with each character other than a letter or digit written as a dash. The change clock reads the time of the newest entry in the worktree's HEAD reflog, not the reflog file's modification time, because git gc rewrites the reflog of every worktree at once. A Codex chat keeps the worktree it works in for a day after the last write to its rollout, the file under $CODEX_HOME/sessions/ (~/.codex by default) whose first line names the chat's working directory. A compressed .jsonl.zst rollout counts too. A rollout written in the last day that the scan cannot read keeps every worktree, because its chat could work in any of them. 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 pinned, and either every session that claims it is archived or it has been quiet for a day. A session left open but idle keeps it for that day only. 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, and so is one whose folder lost its .git file and holds no files. Agents make worktrees in the app's .claude/worktrees and a temp or scratch folder, and older runs left them in the run directory.
ASK for a worktree: it sits outside those folders, another worktree lives inside it, it holds a submodule or nested repository with changes, it holds an ignored file the checkout lacks, it holds a commit no branch, tag or remote reaches whose changes the checkout lacks, or its folder lost its .git file and still holds files, which git can no longer read. An ignored file counts because the patch --delete saves leaves ignored files out. In a pstack project only files under <plans>/artifacts/ count, as for --landed. A worktree with more than 20,000 ignored files to compare is asked about too.
KEEP for a cache: a running server holds its dev/lock or lock. Outside a run folder, a build output (.next or .next-plite) never goes, because next start may serve it. Its dev and cache folders, which Next recreates, get rows of their own instead: KEEP while a server holds the build output's lock or something wrote within two levels of the folder in the last day, and SAFE after that. Any other .next-* folder is judged whole: KEEP for a week after its last use when it holds a production build (BUILD_ID) or is a port's dev cache (.next-<port>), for an hour otherwise, and SAFE after that. A cache inside a safe worktree goes with that worktree.
- A run folder is each folder in
<plans>/artifacts/ of a pstack project, whose .agents/pstack.json names its plans directory. Each folder in an ignored .tmp/ at a checkout's root, where runs left scratch copies, is one too, in any project. It gets a row only when it holds an install or build (node_modules, .next, .next-* or .turbo) or nothing wrote it for a week. Its quiet time reads only file writes outside those folders. KEEP when a worktree lives inside it, a running process works in it or something wrote it in the last day. SAFE with expire, which deletes the whole folder, when nothing wrote it for a week and neither the ledger nor a decision log in <plans>/ changed that week names it, because a new row may still cite its files as proof. A clone inside it blocks expire when it holds commits no remote has, such as a stash or any commit of a clone with no remote, or when git cannot read it, such as a worktree copy its repository dropped. Such a folder is SAFE with strip while it holds installs or builds, and ASK after that. Before --delete expires a folder, it saves each clone's uncommitted changes as a patch under the repository's git folder, in cleanup/, as it does for a worktree's. The patch holds each file git does not ignore, every one of them in a repository with no commit yet, and the ignored ones, such as installs, builds and env copies, go with the folder. Otherwise SAFE with strip, which deletes only its installs and builds and keeps its logs. The scan never touches a file at the top of <plans>/artifacts/ or .tmp/, such as the ledger or a rendered plan page.
- 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.
- 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.
- Record
df -h <checkout> again and report the space freed from the two df readings, because du counts the hard links and APFS clones 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 session leaves its own worktree once its task lands, as the chips Landing rule says, so the scan finds those after their quiet day, along with proof worktrees a run left behind, dev caches and subagent worktrees. Claude Code names a subagent's worktree agent-<id>, locks it while the subagent runs, and keeps it once the subagent has changed a file.
A next dev run spawns a detached process that flushes Next's telemetry and should exit within seconds. When it starts an esbuild service, as a Next config that loads @workflow builders does, it never exits, and the scan keeps the worktree it works in. If a KEEP row's processes have parent PID 1 and run next/dist/telemetry/detached-flush.js, stop them, run next telemetry disable once so no new ones start, and scan again.
1---2name: cleanup3description: "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."4argument-hint: '[scan|all]'5metadata:6 source: https://skillmd.com/skills/udecode/cleanup7---89# Cleanup1011pstack'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. In a pstack project, whose `.agents/pstack.json` names its plans directory, it counts only ignored files under `<plans>/artifacts/`, where a file counts once the checkout has its path, and skips commits only HEAD's reflog reaches, because there every other ignored file is build output or a copy and a landed squash leaves its originals in the reflog. 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 and then leaves its worktree for the scan. 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. They hold it back only while the commit writes a file whose content neither the checkout's HEAD nor its upstream has and neither changed since, so the commits a squash landing leaves behind do not, and `--delete` saves them as a patch before it removes the worktree. `--remove` saves it instead, because a card session commits its work in its own worktree and lands the same change here as a patch.1213`/cleanup scan` lists and removes nothing. `/cleanup` removes the safe set. `/cleanup all` removes it in every checkout beside this one, such as each repository in `~/git`. Its steps 3 and 4 pass `--repos <that folder>` instead of `--repo .`, and the scan judges each checkout there that has linked worktrees against one session list. Schedule `/cleanup all` to run each day. One busy repository gained about ten subagent worktrees a day. `du` puts each at 2 GB or more, but on APFS a pnpm install clones the package store's files, so the space a worktree alone uses is mostly its builds and dev caches, 0.2 to 8 GB.1415A project's session-start hook can run `scan.mjs --brief --auto`. Besides the hint line, it starts `--delete` in the background at most once a day per clone, from the session's own worktree, which that run keeps. It passes no session list, so only a running process, a lock, a server or the day's writes keep a worktree, and it removes only the `SAFE` set, while the `ASK` rows wait for `/cleanup`. Each start rewrites `cleanup/last-run` in the repository's git folder, which then holds the run's report. A user turns the run off with the line `auto cleanup: off` in `~/.claude/pstack-models.md`, and `git worktree lock --reason "<why>" <path>` keeps one worktree.16171. Record `df -h <checkout>`. On macOS, `df -h /` reports the read-only system volume, not the data volume that holds the checkout.182. 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, a worktree that an idle session left open goes after a quiet day, as in the session-start run below.193. 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.20 - `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 also stays for a day after its last change or after the last write to a transcript of a session working in it, or of the session whose scratch folder holds it, unless every session that claims it is archived. Claude Code keeps the first kind of transcript in a folder of its `projects` folder named for the worktree path, with each character other than a letter or digit written as a dash. The change clock reads the time of the newest entry in the worktree's HEAD reflog, not the reflog file's modification time, because `git gc` rewrites the reflog of every worktree at once. A Codex chat keeps the worktree it works in for a day after the last write to its rollout, the file under `$CODEX_HOME/sessions/` (`~/.codex` by default) whose first line names the chat's working directory. A compressed `.jsonl.zst` rollout counts too. A rollout written in the last day that the scan cannot read keeps every worktree, because its chat could work in any of them. The scan also keeps it when `lsof` cannot answer.21 - `SAFE` for a worktree: it sits where agents make worktrees and nothing above keeps it. No session that claims it is running or pinned, and either every session that claims it is archived or it has been quiet for a day. A session left open but idle keeps it for that day only. 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, and so is one whose folder lost its `.git` file and holds no files. Agents make worktrees in the app's `.claude/worktrees` and a temp or scratch folder, and older runs left them in the run directory.22 - `ASK` for a worktree: it sits outside those folders, another worktree lives inside it, it holds a submodule or nested repository with changes, it holds an ignored file the checkout lacks, it holds a commit no branch, tag or remote reaches whose changes the checkout lacks, or its folder lost its `.git` file and still holds files, which git can no longer read. An ignored file counts because the patch `--delete` saves leaves ignored files out. In a pstack project only files under `<plans>/artifacts/` count, as for `--landed`. A worktree with more than 20,000 ignored files to compare is asked about too.23 - `KEEP` for a cache: a running server holds its `dev/lock` or `lock`. Outside a run folder, a build output (`.next` or `.next-plite`) never goes, because `next start` may serve it. Its `dev` and `cache` folders, which Next recreates, get rows of their own instead: `KEEP` while a server holds the build output's lock or something wrote within two levels of the folder in the last day, and `SAFE` after that. Any other `.next-*` folder is judged whole: `KEEP` for a week after its last use when it holds a production build (`BUILD_ID`) or is a port's dev cache (`.next-<port>`), for an hour otherwise, and `SAFE` after that. A cache inside a safe worktree goes with that worktree.24 - A run folder is each folder in `<plans>/artifacts/` of a pstack project, whose `.agents/pstack.json` names its plans directory. Each folder in an ignored `.tmp/` at a checkout's root, where runs left scratch copies, is one too, in any project. It gets a row only when it holds an install or build (`node_modules`, `.next`, `.next-*` or `.turbo`) or nothing wrote it for a week. Its quiet time reads only file writes outside those folders. `KEEP` when a worktree lives inside it, a running process works in it or something wrote it in the last day. `SAFE` with `expire`, which deletes the whole folder, when nothing wrote it for a week and neither the ledger nor a decision log in `<plans>/` changed that week names it, because a new row may still cite its files as proof. A clone inside it blocks `expire` when it holds commits no remote has, such as a stash or any commit of a clone with no remote, or when git cannot read it, such as a worktree copy its repository dropped. Such a folder is `SAFE` with `strip` while it holds installs or builds, and `ASK` after that. Before `--delete` expires a folder, it saves each clone's uncommitted changes as a patch under the repository's git folder, in `cleanup/`, as it does for a worktree's. The patch holds each file git does not ignore, every one of them in a repository with no commit yet, and the ignored ones, such as installs, builds and env copies, go with the folder. Otherwise `SAFE` with `strip`, which deletes only its installs and builds and keeps its logs. The scan never touches a file at the top of `<plans>/artifacts/` or `.tmp/`, such as the ledger or a rendered plan page.254. 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`.265. 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.276. Record `df -h <checkout>` again and report the space freed from the two `df` readings, because `du` counts the hard links and APFS clones a package store shares once per folder. Then report what went and each row kept or asked, with its reason.2829Run it once in each project checkout whose worktrees or caches the owner wants gone. A session leaves its own worktree once its task lands, as the chips Landing rule says, so the scan finds those after their quiet day, along with proof worktrees a run left behind, dev caches and subagent worktrees. Claude Code names a subagent's worktree `agent-<id>`, locks it while the subagent runs, and keeps it once the subagent has changed a file.3031A `next dev` run spawns a detached process that flushes Next's telemetry and should exit within seconds. When it starts an esbuild service, as a Next config that loads `@workflow` builders does, it never exits, and the scan keeps the worktree it works in. If a `KEEP` row's processes have parent PID 1 and run `next/dist/telemetry/detached-flush.js`, stop them, run `next telemetry disable` once so no new ones start, and scan again.