About macos-disk-cleanup
macOS Disk Cleanup is a guided skill for measuring disk usage and removing reclaimable files on macOS. It separates rebuildable quick wins from data that needs individual approval, then checks the space reclaimed.
Key features
- 01Measure disk and directory usage
- 02Classify deletions by risk
- 03Run safe cleanup commands
- 04Request approval for sensitive data
- 05Compare disk usage before and after
Use cases
- 01Finding large directories on a Mac
- 02Clearing rebuildable development caches
- 03Reviewing app data before deletion
- 04Checking cleanup results and snapshots
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/macos-disk-cleanupin Claude Code to confirm it loaded.
Bundled filesagents/openai.yamlreferences/paths.md
Details
From the project READMEmacOS Disk Cleanup
Measure before deleting, spend the safe wins first, and treat anything holding local-only state as confirm-first — it needs the user's explicit go-ahead, because nothing re-downloads it.
Process
- Measure top-level and home usage.
- Drill into the largest user-owned directories.
- Classify every candidate as a quick win or confirm-first, and present the two groups separately.
- Run the quick wins; ask before each confirm-first deletion.
- Re-measure and report the delta.
Done when every consumer above ~1G is classified, each confirm-first deletion was individually approved, and a before/after df -h / frames what the run actually freed.
Measure
# 1. Top-level
du -sh /System /Users /private /Applications /Library 2>/dev/null | sort -rh
# 2. Home breakdown
du -sh ~/Library ~/Code ~/Downloads 2>/dev/null | sort -rh
# 3. Library breakdown
du -sh ~/Library/Application\ Support/* ~/Library/Caches/* ~/Library/Group\ Containers/* 2>/dev/null | sort -rh | head -20
Aim the drill-down with the user's profile:
| Profile | Check first | Typical gain |
|---|---|---|
| Developer | Homebrew, uv/npm/pip, DerivedData, simulators | 10–20G |
| AI/ML user | Ollama unused models, HuggingFace, LM Studio | 5–15G |
| Chrome-heavy | OptGuideOnDeviceModel, GoogleUpdater | ~5G |
Quick Wins
Everything here rebuilds or re-downloads on demand — run without asking.
| Command | Frees | Notes |
|---|---|---|
brew cleanup --prune=all | 2–10G | Cached installers |
uv cache clean --force | 1–10G | uv package cache |
npm cache clean --force | 500M–2G | npm cache |
pip3 cache purge | 100–500M | pip cache |
pre-commit clean | 200–500M | pre-commit envs |
rm -rf ~/Library/Developer/Xcode/DerivedData | 500M–5G | Rebuilds on demand |
xcrun simctl delete unavailable | 1–10G | Unused iOS simulators |
Path catalog
For the per-path verdicts — Chrome, AI model caches, dev tool caches, and the confirm-first app data — read references/paths.md before proposing any deletion outside the quick wins above.
After Cleanup
df -h / lags because APFS local snapshots still hold the freed blocks. Check tmutil listlocalsnapshots / and tell the user they thin themselves within ~24h — the number is already correct underneath, so the next move is to wait rather than clean again.