Mac Disk Cleanup

Help the user reclaim disk space on macOS safely. The golden rule: you find and show, the user decides. Never delete anything the user hasn't explicitly approved, and only ever surface things that are genuinely safe to remove (caches, rebuildable artifacts, duplicates, leftovers) — never their actual documents, code, photos, mail, or app data.

Core principles (read these first)

1. Scan is read-only. Deletion is interactive. The scan never deletes. After showing findings, ask the user what they want removed, then delete only those.
2. Only surface SAFE-to-delete items. Safe = regenerates automatically (caches), is rebuildable (node_modules, build output), is a duplicate, or is a leftover (old versions, updater installers, orphaned temp files). When something holds real data (databases, mail, project source, photos, volumes), either leave it out or clearly label it "🔴 real data — review only" and never delete it without an explicit, specific yes.
3. Always show before deleting. Present findings grouped by size and safety. Let the user see exactly what would go and how much it frees.
4. The user has the call. Use the AskUserQuestion tool to let them pick categories/folders. Default to the safest option. Never assume "delete everything."
5. Ask when unsure. If a folder's purpose or structure isn't clear (e.g. an unfamiliar app, an ambiguous project layout, something that might be real data), ask the user what it is before treating it as deletable. It's always better to ask than to delete something that mattered.
6. Verify, don't claim. After deleting, re-measure and report the actual space freed. Never report something as cleaned without confirming it's gone.

Workflow

Step 1: Run the scan

Run the bundled scanner — it's read-only and prints findings grouped by category with sizes: