macOS Disk Cleanup

Recover disk space on macOS by cleaning caches, dev tool artifacts, stale dependencies, logs, and other reclaimable storage. Developer-focused — knows where the real space hogs hide on a dev machine.

Core Philosophy

1. Analyze before deleting. Always scan first. Show the user what's consuming space and how much can be reclaimed before touching anything.
2. Risk-aware cleanup. Categorize targets by risk (safe → low → moderate → high). Clean safe items freely, require confirmation for everything else.
3. Use built-in cleanup commands. Prefer brew cleanup, npm cache clean, xcrun simctl delete unavailable over raw rm -rf. Tools know their own cleanup semantics better than we do.
4. Never touch user data. Documents, Desktop, Pictures, credentials, SSH keys, keychains, git repos — hands off. Always.
5. Report results. After cleanup, show before/after disk space comparison.

Quick-Start

"My disk is full, help me clean up"

Step	Action
1	Run scripts/analyze-disk.sh to scan all targets
2	Review report — prioritize by size and risk
3	Clean safe targets first (caches, logs, DerivedData)
4	Present moderate targets for user confirmation
5	Only mention high-risk targets if user asks
6	Show before/after disk space comparison

"Clean everything safe"

Execute safe-tier cleanup in order:

1. User caches (rm -rf ~/Library/Caches/*)
2. User logs (rm -rf ~/Library/Logs/*)
3. Xcode DerivedData (rm -rf ~/Library/Developer/Xcode/DerivedData/*)
4. Simulator caches (rm -rf ~/Library/Developer/CoreSimulator/Caches/*)
5. Homebrew (brew cleanup --prune=all && brew autoremove)
6. npm/yarn/pip caches (npm cache clean --force, etc.)
7. Diagnostic reports
8. Saved Application State

"What's using all my space?"

Run analysis only — no cleanup:

bash scripts/analyze-disk.sh

Or for machine-readable output:

bash scripts/analyze-disk.sh --json

Cleanup Priority Order

Targets ordered by typical space savings (highest ROI first):

Priority	Target	Typical Savings	Risk
1	Xcode DerivedData + simulators	10-80 GB	Safe
2	Docker images + build cache	10-80 GB	Moderate
3	Stale node_modules	5-50 GB	Moderate
4	Rust target/ directories	5-50 GB	Moderate
5	User caches (all apps)	2-20 GB	Safe
6	Homebrew cleanup	1-8 GB	Safe
7	Package manager caches	3-15 GB	Safe
8	Gradle/Maven caches	3-13 GB	Safe
9	iOS Device Support (old)	2-30 GB	Low
10	Trash	0-50 GB	Moderate
11	Logs & diagnostic reports	0.5-5 GB	Safe
12	iOS device backups	5-100 GB	High

Decision Trees

What to Clean Based on User Request

User Says	Action
"Clean up my Mac"	Full scan → report → clean safe → confirm moderate
"Clean caches"	User + system caches, browser caches, dev tool caches
"Clean dev tools"	npm/pip/cargo/brew/xcode/docker/gradle caches only
"What's using space?"	Analysis only, no cleanup
"Clean Docker"	docker system prune -a (confirm first)
"Clean Xcode"	DerivedData + simulators + old device support
"Free up X GB"	Prioritized cleanup until target is reached
"Clean everything"	Full cleanup including moderate-risk targets

Docker Cleanup Levels

Level	Command	Cleans	Risk
Light	docker container prune && docker image prune	Stopped containers + dangling images	Low
Medium	docker system prune -a	All unused images + containers + networks	Moderate
Heavy	docker system prune -a --volumes	Everything + volumes (data loss!)	High

Note: Docker Desktop's VM disk (Docker.raw) doesn't shrink after cleanup. To reclaim host disk space: Docker Desktop → Settings → Resources → reduce disk limit, or Troubleshoot → Clean/Purge Data.

Time Machine Local Snapshots

If disk space wasn't freed after deletion, local TM snapshots may be holding references:

SUDO="${SUDO:-$(command -v sudo)}"   # override: SUDO="" or SUDO=doas
tmutil listlocalsnapshots /
$SUDO tmutil deletelocalsnapshots <date>

Safety Rules

Never touch these paths:

• ~/Documents, ~/Desktop, ~/Pictures, ~/Music, ~/Movies
• ~/Library/Keychains/, ~/Library/Accounts/
• ~/.ssh/, ~/.gnupg/, ~/.aws/, ~/.kube/, ~/.config/gcloud/
• /System/, /usr/, /bin/, /sbin/
• ~/.cargo/bin/ (installed Rust binaries, not cache)
• Any .git/ directory
• ~/Library/Mail/ (use Mail.app for mail cleanup)
• iCloud files (use brctl evict or Finder, never rm)

See references/safety-protocols.md for detailed safety rules and confirmation flow patterns.

After Cleanup

Always verify space was freed:

df -h /
diskutil info / | grep -E "(Free|Available|Purgeable)"

If space wasn't freed, check Time Machine local snapshots (see above).

Reference Files

File	Contents
references/cleanup-targets.md	Exhaustive list of cleanup targets with exact paths, commands, risk levels, and typical space savings for each category
references/safety-protocols.md	Golden rules, confirmation flow patterns per risk level, paths to never touch, pre-cleanup checklist, recovery procedures
references/space-analysis.md	Disk usage analysis techniques, scan/report/clean workflow, finding large files, stale node_modules/Rust targets, Docker analysis, recommended CLI tools

Scripts

Script	Usage
scripts/analyze-disk.sh	Scans all known cleanup targets, reports sizes and risk levels. Flags: --json (JSON output), --dev-only (dev caches only), --quick (skip slow scans)