Clean Caches

Reclaim disk space on macOS and Linux. Progressive cleanup grouped by risk tier.

Process

1. Triage. Run df -h / and du -sh ~/Library/Caches ~/.cache /var/cache/apt /var/cache/dnf /Users/Shared/OrbStack ~/Library/Developer 2>/dev/null to size up. Report top space consumers.
2. Offer tiers to user — let them pick scope:
   • Safe — package manager caches + Homebrew (no rebuild cost beyond download)
   • Medium — Docker/OrbStack/Xcode caches (rebuild cost: minutes)
   • Project — project node_modules, .next/dist build artifacts (rebuild cost: seconds-minutes; don't bulk-rm ~/code/; use project tooling)
   • Risky — macOS Library caches, browser caches (may sign you out / lose state)
   • Destructive — Trash emptying, OrbStack VM reset (confirm each)
3. For each chosen op: state what'll be removed, run it, report bytes freed.
4. Final report: before/after df -h / and total reclaimed.

Rules

• Default to safe + medium if user says "clean up" without specifying.
• Never run destructive ops without explicit confirmation from the user this session.
• Skip categories with <100MB to reclaim (not worth the time).
• Don't touch ~/code/ repos directly. Project-level cleanup goes through the project's own tooling (pnpm, etc.), not by rm -rf node_modules for arbitrary dirs.
• Track cumulative bytes freed; report at end.

Quick mode

If user says "just do the safe stuff" or "/clean-caches safe":

macOS: pnpm/npm/yarn/bun caches, Homebrew (brew cleanup -s), Xcode unavailable simulators, macOS DNS cache flush Linux: pnpm/npm/yarn/bun caches, apt/dnf/pacman cache clean, journalctl vacuum Skip prompts; report freed space at end.

OS detection

Run once at start to route commands:

case "$(uname -s)" in
  Darwin) echo "macos" ;;
  Linux)
    if [ -f /etc/os-release ]; then . /etc/os-release; echo "linux:$ID"
    else echo "linux:unknown"; fi ;;
  *) echo "unknown" ;;
esac

Routing table

See COMMANDS.md for full commands per tier.

Tool checks

Detect before running:

• command -v docker / command -v orb (OrbStack)
• command -v pnpm / npm / yarn / bun
• command -v brew
• command -v xcrun

If a tool isn't present, skip its category.