/disk-cleanup

name: disk-cleanup
compatibility: "Claude Code 2.1.277+. macOS or Linux, Python 3.9+, git. Optional: gh, docker, lsof."
description: "Frees the disk that agents and worktrees leave behind: caches, merged worktrees, Docker build cache, old logs. Dry run lists safe, regenerable and ask-first items with sizes; --apply after you confirm. Use when the disk is nearly full. Never deletes branches."
license: MIT
argument-hint: "[--apply] [--only ID] [--tier safe|regenerable] [--root DIR] [--json]"
user-invocable: true
disable-model-invocation: false
effort: low
allowed-tools: Bash, Read, AskUserQuestion
metadata:
  category: devops
  version: "1.0.0"
  author: "OrchestKit"
  complexity: "low"
  tags: "disk, cleanup, worktrees, caches, docker, agents, macos, linux"

disk-cleanup, get the disk back from your agents

Running many agents and worktrees fills a disk fast: a fresh `node_modules` per worktree, a build cache per tool, Docker layers, browser downloads, session logs. This skill finds all of it, sorts it by how safe it is to remove, and removes only what is provably safe, after you confirm.

Critical rules

1. **Dry run first, always.** Run the script without `--apply`, show the inventory, and get an explicit yes from the user in the conversation before any `--apply`. 2. **`--apply` touches two tiers only.** SAFE (caches that refill on their own) and REGENERABLE (merged, clean, idle worktrees; rebuildable stores). ASK FIRST items are listed with the command to run. The script never runs them and neither do you without the user naming the item. 3. **Unreadable is KEEP.** A failed `git`, `gh`, `lsof` or `docker` call keeps the item and says why. Never remove on a guess. 4. **A worktree is removed only when all of these hold:** its tip is on the default branch (or equals the head of a merged PR), the tree is clean, it holds no ignored file outside a rebuildable folder (`node_modules`, `.venv`, `dist`, `build`, `.next`, `__pycache__` and the like; an ignored `.env.local` keeps the tree), it is not locked, no process has its working directory inside, nothing in it changed for 60 minutes, and it sits under the home directory. Removal is `git worktree remove` without force. The branch stays. 5. **Report the measured number.** The freed total is free space before versus after. The inventory total is an estimate and is labelled as one.

Instructions

1. Dry run. From a repo you work in (the script scans its worktrees) or with `--root DIR` for a folder that holds several repos:

   python3 "${CLAUDE_SKILL_DIR}/scripts/disk_cleanup.py"
   python3 "${CLAUDE_SKILL_DIR}/scripts/disk_cleanup.py" --root ~/code

Exit 0 means nothing to clean, 3 means findings, 2 means it could not look. 2. Show the user the inventory as printed. Lead with the verdict line, then name the three biggest rows and any KEEP lines that explain why a worktree was left alone. 3. Ask the user to confirm. Offer the narrower forms when they hesitate: `--tier safe` (caches only) or `--only npm-cache` (one item id, or a section such as `docker`). 4. Apply with the command the dry run printed under "To act on exactly this list". It pins `--only` to the ids the user just saw, so anything that became removable after the dry run (a worktree that merged or went idle meanwhile) is left alone:

   python3 "${CLAUDE_SKILL_DIR}/scripts/disk_cleanup.py" --apply --only npm-cache --only 'worktree:/path/to/tree'
   python3 "${CLAUDE_SKILL_DIR}/scripts/disk_cleanup.py" --apply --tier safe

Expected: one line per action (done or failed), then `freed (measured, before and after)`. 5. For ASK FIRST rows, read the user the printed command and what it removes. Run it only when they confirm that specific row. 6. Optional: `--json` for a machine-readable inventory, `--report FILE` to save it. The report starts with a marker line and the script refuses to overwrite a file without it.

What counts as what

| Tier | Meaning | Examples | |---|---|---| | 🟢 SAFE | Pure cache, the tool refills it | npm, pip, uv, Cargo, Go caches, Homebrew downloads, Xcode DerivedData, browser caches, Docker build cache and dangling images, agent debug logs older than 14 days | | 🟡 REGENERABLE | Rebuilds, but costs time or bandwidth | merged worktrees, pnpm store, Playwright browsers, unused Docker images | | 🔴 ASK FIRST | Might be someone's work | unmerged or detached worktrees, session transcripts, Downloads, Trash, Docker volumes, orphan agent processes |

Full path list per OS and the evidence behind each gate: `references/catalog.md`.

Example output

disk-cleanup dry run: 47.1 G reclaimable, 24.0 G more needs you

DISK  ~  (macOS)
[▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░]
 used 355.0 G    free 73.0 G    83 % full · 460.0 G total
────────────────────────────────────────────────────────────────────────
🟢 SAFE  caches that refill on their own
────────────────────────────────────────────────────────────────────────
🐳 Docker build cache                 ▓▓▓▓▓▓▓ 14.5 G  prune
🌐 Browser caches                     ▓▓▓▓░░░  8.9 G  clear
📦 npm cache                          ▓▓▓░░░░  6.2 G  clear
                                         ── 29.6 G
────────────────────────────────────────────────────────────────────────
🟡 REGENERABLE  merged worktrees and rebuildable stores
────────────────────────────────────────────────────────────────────────
🗂️ app/fix-login  merged PR #412      ▓▓▓▓░░░  3.9 G  remove
        KEEP  app/hotfix-7  dirty (3 files)
        KEEP  app/agent-3  process cwd inside (pid 4121)
🟢 29.6 G + 🟡 3.9 G = 33.5 G estimated  →  free 73.0 G → ~106.5 G
ℹ️  Sizes are allocated blocks, so sparse files read small.

Examples

User says: "my disk is almost full, I run a lot of agents". Actions: run the dry run, show the inventory, ask to confirm, run `--apply`. Result: SAFE and REGENERABLE items removed, a measured freed total, ASK FIRST rows left for the