Macos Cleanup

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 only on explicit ask.

Categories

User/system junk (mostly safe)

• ~/Library/Caches/* — per-entry, not wholesale. Skip entries of currently running apps (pgrep -if ) 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 ""'.

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 . Check pyenv version first — never remove the active one.
• Sparkle PersistentDownloads (old app-update packages under ~/Library/Caches//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)/ + 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pivoshenko
• Source: pivoshenko/pivoshenko.ai
• License: MIT
• Homepage: https://ai.pivoshenko.dev

Install and usage instructions live in the source repository linked above.