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.
caches; the only cost is a slower next build/install.
rm. Ask-tier items, app leftovers, bigfiles — 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.
license, an unpushable Xcode archive, or someone's only local backup is not.
~/Library/Logs/mac-storage-cleaner/operations.log.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.
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.
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), runsbrew 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.
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 system prune -a, never rm the VM disk.xcrun simctl delete unavailable is safe; deleting active devices wipes state.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.
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.
Read references/cache-catalog.md for the full tiered inventory and gotchas. The essentials:
(~/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.
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.
sudo into /System, /Library/Caches, /private/var/folders, orSIP-protected areas — that's macOS's job.
~/.cargo (has installed binaries — only clearregistry/), ~/.m2 (has settings.xml — only clear repository/), ~/.gradle
(only caches/). ~/.npm is pure cache so it's fine whole.
du; rm -rf on multiple paths keepsgoing after a failure, so never assume total success or total failure.