macOS Cleanup

Deep-clean: junk + app leftovers + dev junk + space/startup audit. Destructive territory -> scan (read-only) -> sized report -> confirm -> delete -> verify freed. Never delete during scan.

Flow

1. Scan: bash scripts/scan.sh. Read-only, deletes nothing. Sized report -> stdout, raw lists -> /tmp/macos-cleanup-scan.*/ (path printed). du over ~/Library = takes a minute+, warn user up front
2. Cross-ref leftovers: installed.txt (app bundle ids + cask/formula names) vs candidates (app-support.txt, containers.txt, preferences.txt, caches.txt, saved-state.txt, LaunchAgents). Matching rules below. Flag only what you can name the dead app for
3. Report: table per category - item · size · verdict (safe = regenerable / risky = judgment call / skip + why). Lead with total reclaimable + current disk free
4. Confirm: AskUserQuestion, multiSelect across categories. Anything >1 GB or non-regenerable (iOS backups, go modcache, simulator runtimes, Xcode DeviceSupport) -> its own option, never bundled into a category
5. Clean: only what was confirmed, commands below. Leftovers + launch agents -> Finder Trash (recoverable). Pure caches -> rm fine
6. Verify: df -h / before vs after -> "freed X GB". List skipped + why. df unchanged -> likely APFS purgeable / TM local snapshots; report tmutil listlocalsnapshots /, thinning is automatic, tmutil deletelocalsnapshots <date> only on explicit ask

Categories

User/System Junk (Mostly Safe)

• ~/Library/Caches/* - per-entry, not wholesale. Skip entries of currently running apps (pgrep -if <name>) or tell user to quit them
• ~/Library/Logs, CrashReporter, QuickLook thumbnails, ~/Library/HTTPStorages - regenerable
• Trash: osascript -e 'tell app "Finder" to empty trash' (handles locked files)
• Mail Downloads cache - safe; Mail data itself off-limits
• iOS device backups (~/Library/Application Support/MobileSync/Backup) - user data, not regenerable. Individual confirm, state device + date per backup (ls -lt)

App Leftovers (Risky - Be Conservative)

Locations: Application Support, Caches, Preferences, Containers, Saved Application State, LaunchAgents, Logs, HTTPStorages.

Matching rules:

• Flag only when owner identifiable AND definitively gone: bundle id / vendor name absent from installed.txt, no running process, not a CLI tool
• Verify, don't assume - grep installed.txt for every candidate before the verdict. Name familiarity ≠ installed (Code = VS Code, not Codex; an app being famous doesn't mean it's present)
• Never flag: com.apple.*, group.*, anything matching an installed app/cask/formula, vendor-shared dirs while any of that vendor's apps remain (e.g. Google, JetBrains, Microsoft)
• Unsure who owns it -> skip + say so. Missed leftover >> deleted-wrong-thing
• Removal -> Trash: osascript -e 'tell app "Finder" to delete POSIX file "<abs path>"'

Dev Junk

• brew: brew cleanup --prune=all && brew autoremove
• docker (daemon must run): docker system prune -f. Never --volumes unless user explicitly says volumes
• Xcode: rm -rf ~/Library/Developer/Xcode/DerivedData; xcrun simctl delete unavailable; old iOS DeviceSupport = risky (re-fetch needs the device)
• Caches: pnpm store prune · npm cache clean --force · pip cache purge · uv cache clean (safe, next install re-downloads; location from uv cache dir - often ~/.cache/uv, not ~/Library/Caches) · cargo registry rm -rf ~/.cargo/registry/{cache,src} (lockfiles re-fetch) · go clean -modcache = risky, slow re-download
• XDG ~/.cache/* (rod, huggingface, etc.): tool caches, mostly regenerable - but identify the owner per entry, same skip-if-unsure rule as leftovers
• pyenv: superseded patch versions (3.13.9 next to 3.13.10) -> pyenv uninstall <old>. Check pyenv version first - never remove the active one
• Sparkle PersistentDownloads (old app-update packages under ~/Library/Caches/<app>/org.sparkle-project.Sparkle/) - safe, apps re-download pending updates
• Stale build dirs (projects.txt): only projects untouched 30+ days. Regenerable via install/build (.next via next build). >500 MB -> per-project confirm. Never touch a repo's tracked files - node_modules/.venv/target/.next only

Optimization / Space Report

• Biggest dirs from scan -> short "what's eating the disk" breakdown
• Login items + LaunchAgents/Daemons: flag dead ones (binary or app in ProgramArguments no longer exists). Removal = launchctl bootout gui/$(id -u)/<label> + plist -> Trash, per-item confirm. Live but unwanted -> report only, let user decide
• No perf snake-oil: no purge, no "free RAM", no repair-permissions theater. Real wins = disk space + fewer startup items

Rules

• Scan phase = read-only. Delete only what the user confirmed this session, nothing more
• Never touch: Documents/Desktop/Photos/iCloud Drive, ~/Library/Keychains, ~/.ssh, Mail data, browser profiles (their Caches ok), dotfiles, any repo's tracked files, /System (SIP anyway)
• No sudo by default. System paths (/Library/Caches, /Library/Logs, LaunchDaemons) -> report; act only on explicit sudo OK
• Anything ambiguous -> skip verdict + one-line reason in report. User can override
• Every scanned category shows up in the report - empty/clean ones as "already clean" (e.g. "Trash: empty"), never silently omitted. Omission reads as "not checked"
• Empty scan (nothing significant) -> say so + stop. Don't invent work
• Never report a finding this file predicts - the verdict comes from the scan, not from here. Baked-in findings are how an audit skill rots