mac-storage-cleaner

Mac Storage Cleaner

Free disk space the way a careful engineer would, and earn the trust one-click cleaners lose: measure first, delete only what provably regenerates, make anything riskier reversible, ask before anything expensive, log every action, and report honestly. The differentiator over CleanMyMac-style tools is judgment and transparency — the user sees what will go and why, and can undo it.

Scripts live in scripts/; the full tiered inventory, exact reclaim commands, and gotchas are in references/cache-catalog.md. Read the catalog whenever you hit something a script didn't classify or you need the precise command.

Core principles

• Safe tier → delete outright (space back immediately). These are pure caches; the only cost is a slower next build/install.
• Everything else → Trash, not rm. Ask-tier items, app leftovers, big files — move them to the Trash with trash-items.sh so the user can restore them. Reversibility is the whole point; never hard-delete a user's data.
• When unsure, demote a tier. A slower rebuild is trivial; deleting a license, an unpushable Xcode archive, or someone's only local backup is not.
• Every destructive run is logged to ~/Library/Logs/mac-storage-cleaner/operations.log.

Workflow

Locating the scripts. The commands below resolve $D to this skill's own directory so they work whether the skill was installed as a plugin ($CLAUDE_PLUGIN_ROOT is set) or as a standalone skill (~/.claude/skills/…). Shell state doesn't persist between commands, so each block re-resolves $D.

1. Survey — caches (always first, read-only)

D="${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/skills/mac-storage-cleaner}"; D="${D:-$HOME/.claude/skills/mac-storage-cleaner}"
bash "$D/scripts/survey.sh"

Prints free space and sizes every cache that exists on this machine, grouped safe / ask / never / app-data. Never skip it — locations and sizes differ on every Mac. Note current free space for the before/after report.

2. Clear the safe tier (no per-item permission needed)

Tell the user briefly what the safe tier removes and roughly how much it frees, then:

D="${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/skills/mac-storage-cleaner}"; D="${D:-$HOME/.claude/skills/mac-storage-cleaner}"
bash "$D/scripts/clean-safe.sh"

Removes only the vetted safe allowlist (nothing else — the survey's "other large caches" list is for the user to review, not for auto-deletion), handles read-only files, skips anything macOS protects (reporting rather than failing), runs brew cleanup -s --prune=all and removes unavailable simulators, logs each deletion, and prints what it reclaimed. If the user only wanted specific items, delete those directly instead.

Browser & Electron app caches (Chrome/Arc/Slack/VS Code/…) are safe but live inside app-data folders — clear only the Cache/Code Cache/GPUCache subfolders the survey lists, ideally with the app quit, and never the whole app folder. Exact paths: references/cache-catalog.md.

3. Surface the "ask" tier — recommend, don't delete

Big but not free caches (Docker images, ML models, simulator devices, Xcode Archives, module stores). List each with size + a specific recommendation; let the user choose. Use the tool-native command, and prefer Trash for file deletions. Key ones (full detail in the catalog):

• Docker — docker system prune -a, never rm the VM disk.
• ML models (HuggingFace/Ollama) — often duplicated variants; offer to remove unused ones.
• Simulators — only xcrun simctl delete unavailable is safe; deleting active devices wipes state.
• Xcode Archives — warn: holds dSYMs for crash symbolication and shippable builds.

4. Go beyond caches — the space the cleaners miss (read-only scan)

D="${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/skills/mac-storage-cleaner}"; D="${D:-$HOME/.claude/skills/mac-storage-cleaner}"
bash "$D/scripts/find-extras.sh"

Surfaces the real hogs a cache sweep ignores: leftover data from uninstalled apps, big files (>500MB), stale installers (.dmg/.pkg), and old Downloads. Everything here is ask-tier — present candidates, let the user pick, then remove reversibly:

D="${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/skills/mac-storage-cleaner}"; D="${D:-$HOME/.claude/skills/mac-storage-cleaner}"
bash "$D/scripts/trash-items.sh" "/path/one" "/path/two"

If trashing reports "could NOT trash (permissions/TCC?)" for every item, the controlling app hasn't been granted Automation control of Finder — a normal first-run state. Tell the user to allow it in System Settings › Privacy & Security › Automation (enable Finder for the terminal/app), then re-run; or move the item to the Trash manually in Finder. Don't report space as freed when items logged trash-failed — nothing was actually removed.

App leftovers need verification. The scan lists containers whose owning app a quick check couldn't confirm is installed — but Spotlight misses un-indexed apps, so some candidates are still installed. Before proposing to remove any leftover, confirm the app is really gone (check /Applications, mdfind, or just ask the user "do you still use X?"), and always Trash it, never rm. To also clear a confirmed-uninstalled app's other leftovers (Preferences, Application Support, Logs, Saved State, etc.), see the leftover-location list in the catalog.

5. Report

In the user's language: before → after free space (df -h /System/Volumes/Data), a short list of what was cleared/trashed with sizes, a one-line note that the first build/install afterward will be slower, the still-large "ask" items each with a recommendation, and the log path.

If free space rose less than the reclaimed size suggests, explain APFS purgeable space: macOS may hold freed space as purgeable (often behind Time Machine local snapshots) and release it on demand — the space is genuinely recovered. Don't chase it with sudo.

Safety rules

Read references/cache-catalog.md for the full tiered inventory and gotchas. The essentials:

• Never delete user data that looks like storage: iOS backups (~/Library/Application Support/MobileSync/Backup), Photos library, Mail/Messages data, whole app-support folders, ~/.ssh/~/.aws/keychains, Time Machine snapshots. Report their size so the user knows, but don't touch them.
• Messaging-app media is user data, not cache. Telegram/WhatsApp/Slack store downloaded photos/videos in their caches. Don't bulk-delete these; point the user to the app's own "Clear Cache" (e.g. Telegram › Settings › Data and Storage › Storage Usage) so they choose what to drop.
• Never sudo into /System, /Library/Caches, /private/var/folders, or SIP-protected areas — that's macOS's job.
• Watch mixed directories: ~/.cargo (has installed binaries — only clear registry/), ~/.m2 (has settings.xml — only clear repository/), ~/.gradle (only caches/). ~/.npm is pure cache so it's fine whole.
• Continue past errors and verify with du; rm -rf on multiple paths keeps going after a failure, so never assume total success or total failure.