mac-cleanup

mac-cleanup

Reclaim disk and RAM on Apple Silicon macOS without breaking anything. This skill is scan-first and confirm-before-delete: it measures, shows the user what is reclaimable and what each item costs to regenerate, and only deletes after an explicit yes.

The bundled scripts live next to this file; invoke them with ${CLAUDE_SKILL_DIR}.

Safety contract — follow every time

1. Measure before you touch anything. Never delete before showing the user a size.
2. On Apple Silicon, read the Data volume, never plain /. Use df -h /System/Volumes/Data

(/ is a sealed read-only system snapshot and understates usage badly).

1. Three tiers (full table in references/cleanup-targets.md):

• SAFE — regenerates automatically, cheap. Fine to batch after one confirmation.
• CAUTION — regenerates but a big/slow re-download or loses state. Confirm each, state the cost.
• NEVER — refuse and explain. Xcode Archives/dSYMs, provisioning profiles, iOS device

backups, Keychain, ~/.ssh/~/.gnupg/~/.aws, iCloud (~/Library/Mobile Documents), and Hugging Face models (~/.cache/huggingface — deliberate multi-GB downloads, not junk).

1. Prefer a tool's own cache-clean subcommand over rm (npm/brew/uv/pip/pod…). Reserve raw

deletion for dirs with no cleaner, and only via the guarded clean.sh.

1. Deletions are not pre-approved. allowed-tools only pre-clears read-only commands, so every

actual delete still prompts the user. Do not add Bash(rm:*).

1. Report the reclaimed delta at the end: re-run df -h /System/Volumes/Data.

Workflow

1 — Measure (read-only)

bash ${CLAUDE_SKILL_DIR}/scripts/scan.sh

Shows true free disk, the biggest app/tool caches, per-toolchain dev caches, and container VMs. Present the biggest reclaimable items to the user, each tagged SAFE / CAUTION with its regen cost.

2 — Reclaim disk (confirm first)

clean.sh is dry-run by default — it prints what it would do until you pass DRY_RUN=0. Every delete flows through a safe_rm guard that refuses any path not strictly under $HOME.

bash ${CLAUDE_SKILL_DIR}/scripts/clean.sh --list          # target keys (SAFE vs CAUTION)
bash ${CLAUDE_SKILL_DIR}/scripts/clean.sh <keys...>       # PREVIEW (no deletion)

Show the preview, get the user's yes, then run for real with the same keys:

DRY_RUN=0 bash ${CLAUDE_SKILL_DIR}/scripts/clean.sh <keys...>

• Batch SAFE keys together after one confirmation (npm pnpm yarn brew pip uv go_build pods sims derived_data gradle_caches trash …).
• Run each CAUTION key only when the user picks it (pub_cache, go_modcache, gradle_dists, maven, docker_prune, colima_stop, …), stating the re-download cost.
• For version-pinned artifacts — Android NDK, emulator system-images/AVDs, rustup toolchains, simulator runtimes — do NOT bulk-delete. First grep the user's projects for pins

(ndkVersion, flutter.ndkVersion, rust-toolchain.toml, gradle-wrapper.properties), keep anything referenced, delete only specific unused versions, and confirm each. See the reference doc.

• Docker: only ever do the safe reclaim — never anything that loses data. Images and build cache are re-creatable; named volumes and the VM hold real data. Use docker system prune (no --volumes) and colima stop (reversible). Do not run — and do not suggest as cleanup — `colima delete`, `docker … --volumes`, or deleting `Docker.raw`; those destroy volumes/the VM (DB data). The colima/Docker VM disk is sparse and won't shrink from safe pruning, so treat that space as not reclaimable — leave it.

3 — Creative-pro & app caches (video / photo / audio / 3D)

Creative caches are the most dangerous category — every app stores regenerable cache inside or next to irreplaceable originals, catalogs, and projects. Follow the golden rules in `references/creative-pro-targets.md`:

1. Prefer the app's own "purge / delete cache" command. For Final Cut (File ▸ Delete Generated

Library Files), Photos (⌘⌥ Repair), Lightroom (Purge Cache / Discard Previews), Logic (Relocate Sound Library), DaVinci Resolve (Delete Render Cache), etc. — there is no safe filesystem command, so tell the user the in-app steps rather than deleting files.

1. Never reach inside a library bundle (.fcpbundle, .photoslibrary, .cocatalog, .logicx,

<Catalog>.lrcat*) — the cache and the only copy of the work share the bundle.

1. For the genuinely-safe, standalone app caches, clean.sh has a CREATIVE target group that

moves files to the Trash (recoverable), not rm. Quit the app first:

   bash ${CLAUDE_SKILL_DIR}/scripts/clean.sh --list                 # see CREATIVE keys
   DRY_RUN=0 bash ${CLAUDE_SKILL_DIR}/scripts/clean.sh adobe_mediacache ae_diskcache browser_cache

Keys: adobe_mediacache, ae_diskcache, camera_raw, bridge_cache, ableton_cache, au_cache, logic_cache, browser_cache, diagnostics, quicklook.

1. Caches are user-relocatable — if the default path is empty, read the configured location from

the app's preferences and confirm that drive is mounted before deleting.

4 — Stop services & analyze RAM (read-only first)

bash ${CLAUDE_SKILL_DIR}/scripts/services.sh

Lists listening dev servers, Homebrew services, container VMs/emulators, and memory health. Before stopping anything: resolve ps -p <PID> -o command= and lsof -a -p <PID> -d cwd, and check it against the DO-NOT-KILL list (ports 5000/7000 = AirPlay/ControlCenter; WindowServer, launchd, coreaudiod, Dock, Finder, the user's editor/browser). Then stop gracefully:

• Databases (Postgres/Redis/…): brew services stop <name> — never kill -9 (risks corruption).
• Android emulator: adb -s <serial> emu kill. Docker VM: colima stop / docker stop <ctr>.
• Generic node/vite/next dev server: kill <PID> (SIGTERM); kill -9 only if it ignores TERM.
• Chrome RAM: many renderers is normal (site isolation). A single multi-GB renderer = one

heavy/leaking tab — identify it in Chrome's Window ▸ Task Manager (⌥⌘Esc) and close/discard that tab or enable Memory Saver. Do not kill renderer PIDs from the shell.

Low "free RAM" on macOS is normal; judge pressure by memory_pressure % + sysctl vm.swapusage (near-full swap is the real "close things" signal).

Notes

• Targets Apple Silicon macOS; Homebrew under /opt/homebrew; 16 KB VM pages.
• The scripts skip machines that lack a given toolchain/app (command -v and existence guards), so they degrade cleanly.
• Full, safety-rated catalogs with every path, command, and trap:
• Developer tools: `references/cleanup-targets.md`
• Creative pros (video/photo/audio/3D) + general apps: `references/creative-pro-targets.md`