disk-space-cleaner

name	disk-space-cleaner
description	Reclaim disk space by finding and deleting regenerable build/dependency directories (node_modules, target, .next, dist, build, .gradle, .turbo) and optionally running `cargo clean` and Docker prune. Dry-run by default, age-gated, and protects git-locked worktrees plus recently-touched work so active sessions are never clobbered. Use when disk is low, when `df` shows the volume near full, or when the user says "clean disk", "free up space", "disk-space-cleaner", or "what's eating my disk".
version	0.1.0
user-invocable	true

disk-space-cleaner

Free disk by deleting only regenerable build/dependency dirs. Never touches source. Dry-run first, always.

Golden rules

1. Diagnose before deleting. Show the user where space went.
2. Dry-run, then apply. The script deletes nothing without --apply.
3. Only regenerable dirs. node_modules (reinstall), target / .next / dist / build / .gradle / .turbo (rebuild). Source is never a target.
4. Protect active work. Skip anything modified in the last N days (default 14) and anything under a git worktree marked locked.
5. Confirm the big irreversible ones (Docker volumes, sudo rm of OS installer leftovers) with the user before running.

Step 1 — diagnose

Find the biggest consumers. Hidden dirs (dotfiles, ~/Library on macOS) are the usual culprits.

df -h .                                        # how full, how much free
du -xh -d 1 "$HOME" 2>/dev/null | sort -rh | head -20
du -xh -d 2 <big-dir> 2>/dev/null | sort -rh | head -25   # drill down

Common hogs: Rust target/ (tens of GB of debug artifacts), per-worktree node_modules/target, Docker.raw, ML model caches (~/.cache/huggingface, ~/.cache/uv), emulator images (~/.android/avd), iOS simulators.

Step 2 — sweep (this skill's script)

# dry-run: list what WOULD be deleted, nothing removed
scripts/clean.sh ~/some/dir ~/another/dir

# apply after reviewing the list
scripts/clean.sh ~/some/dir --apply

# tune age gate + include cargo clean on the newest Cargo project per root
scripts/clean.sh . --older-than 21 --cargo-clean --apply

Flags: --older-than N (days, default 14), --names a,b,c (dir names to target), --max-depth N, --cargo-clean, --no-protect-locked, --apply. Run scripts/clean.sh --help for the full list.

The script prints would rm <size> <path> per dir and a total, protects locked worktrees (skip (locked)), and only removes dirs older than the age gate — so anything you're actively building is left alone.

Step 3 — extras (opt-in, ask first)

These are handy but not in the script because they need judgment or a password:

docker system prune -a -f                      # unused images/containers/build cache
docker volume prune -f                          # ONLY if the user confirms volume data is disposable
uv cache clean;  npm cache clean --force;  pnpm store prune;  yarn cache clean
brew cleanup -s --prune=all
xcrun simctl delete unavailable                 # dead iOS simulators (macOS)
sudo rm -rf "/System/Volumes/Data/macOS Install Data"   # OS installer leftovers (needs sudo)

For Rust specifically, a per-project cargo clean (or --cargo-clean on the script) is the single biggest instant win — target/debug is routinely the fattest deletable dir on the machine.

Safety notes

• A build/ directory is usually generated but can occasionally be source-controlled. Review the dry-run list before --apply; drop it from --names if a project keeps source there.
• Deleting node_modules/target in a worktree where an agent session is mid-build breaks that build. The age gate handles this (recent = active), but when in doubt, check for running sessions first.
• Everything this skill deletes is rebuilt by cargo build, npm/pnpm/yarn install, or the next build — no permanent loss.