mac-storage-doctor

A Claude Code skill that deeply analyzes a Mac's disk usage and tells you exactly what's safe to delete — without ever deleting anything until you say so.

macOS's own About This Mac → Storage panel is notoriously misleading: its "Documents" and "Applications"/"System Data" categories don't map to the folders they're named after, and the actual weight is usually hiding in dev-tool caches, orphaned app data, and forgotten package-manager stores instead. This skill does its own filesystem-level investigation and gives you a straight answer.

What it finds

• Orphaned app data — leftover Application Support/Container/Caches folders for apps you already uninstalled, detected by cross-referencing every folder against what's actually still installed (via Spotlight's mdfind).
• Regenerable dev-tool caches — npm, pnpm, uv, pip, Homebrew, node-gyp, Go build/module cache, Electron caches, browser HTTP caches — anything that just redownloads or rebuilds automatically.
• Rarely-used apps — surfaced with their actual last-used date and use count (via mdls), not just a guess.
• Large, old files — anything big and untouched for months, excluding noise from dev-tool directories already covered elsewhere.
• Ambiguous/unknown folders — resolved to their real vendor identity via Preferences plists, LaunchAgents, and bundle-ID lookups, and checked against launchctl to make sure nothing that's actually a live background service gets miscategorized as safe.

What it won't do

• Never deletes anything without your explicit confirmation. You can approve a whole category, cherry-pick specific rows, or ask for more research on anything ambiguous — silence is never treated as approval.
• Never runs sudo or attempts privilege escalation. Root-owned paths (like parts of /Library/Developer) are reported with the exact command for you to run yourself.
• Never touches a sandboxed app Container via shell. macOS blocks this at the OS level (containermanagerd) even for orphaned apps — those get Finder-based removal steps instead.
• Never batches deletions. One path per command, always — smaller blast radius if anything ever goes wrong.

Output

One synthesized report, every time — a single markdown table:

Item	Size	Category	Justification
...	...	auto-safe / needs-your-call / do-not-touch	...

with a subtotal per category and a grand total, opened and closed with the real free-space number from diskutil info / (not df, which reports confusingly on APFS).

How it works

Four research subagents run in parallel, each covering a distinct slice of the disk:

• Agent A — ~/Library sweep (Application Support, Caches, Containers, Group Containers) + orphan detection
• Agent B — package-manager caches, Homebrew, pipx, nvm, cargo/rustup, Xcode Command Line Tools, CoreSimulator
• Agent C — large/old files, git repo bloat, rarely-used apps
• Agent D — always-on ambiguity resolver: independently verifies anything unrecognized via LaunchAgents/LaunchDaemons, Preferences plists, and bundle-ID lookups before it can be marked safe

Their findings are synthesized into one report, gated behind your confirmation, and only then acted on — one path at a time, with automatic handling for read-only cache permissions (chmod before rm) and clear manual instructions for anything that needs your own sudo or Finder.

Install

git clone https://github.com/SomSamantray/mac-storage-doctor.git ~/.claude/skills/mac-storage-doctor

Or copy the folder directly into ~/.claude/skills/.

Use

In Claude Code, just ask naturally:

"What's taking up space on my Mac?" "Help me free up disk space" "Clean up my Mac"

The skill triggers automatically, or invoke it directly if your setup supports named skill invocation.

Requirements

• macOS (uses mdfind, mdls, diskutil, launchctl — all Spotlight/macOS-specific)
• Claude Code with subagent dispatch support

Safety note

This skill was built from a real, live cleanup session and encoded the lessons learned the hard way — including a Spotlight-indexing blind spot that could otherwise flip its main safety signal backwards, and several safety floors that keep ambiguous items out of the "safe to delete" bucket by default. See references/playbook.md for the full categorization rules.

License

MIT