clean-caches

name	clean-caches
description	Reclaim disk space by cleaning macOS/Linux dev caches (Docker/OrbStack, package managers, Xcode, Homebrew, kilter, browser caches). Tiered by risk — safe ops run by default, destructive ops require confirmation. Use when the user mentions disk pressure, full disk warnings, "clean up", "free space", or invokes /clean-caches.
model	inherit
allowed-tools	["Bash","Read"]
user-invocable	true

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 — kilter cache, 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.

See [[COMMANDS.md]] for the full command matrix per tier.

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, kilter destroy, etc.), not by rm -rf node_modules for arbitrary dirs.
• Track cumulative bytes freed; report at end.
• For kilter cache (~/.cache/kilter/), prefer kilter destroy per-project over wholesale wipe — preserves snapshots and persistent volumes.

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

Category	macOS	Linux (Debian/Ubuntu)	Linux (Fedora)	Linux (Arch)
Pkg mgr caches	pnpm/npm/yarn/bun/pip/uv	same + apt clean	same + dnf clean all	same + pacman -Scc
Homebrew	brew cleanup -s	skip	skip	skip
Nix store	nix-collect-garbage -d (>7d), /tmp/nix-build-*	same	same	same
DNS flush	dscacheutil -flushcache	systemd-resolve --flush-caches	same	same
Docker	docker system prune -a	same	same	same
OrbStack	docker system prune -a + orb disk compact	skip	skip	skip
Xcode	simctl, DerivedData, Archives	skip	skip	skip
App caches	~/Library/Caches/*	skip	skip	skip
System caches	skip	/var/cache/apt	/var/cache/dnf	/var/cache/pacman
Logs	~/Library/Logs/*	journalctl --vacuum-*	same	same
Browser profiles	~/Library/Application Support/	~/.config/	same	same
Empty trash	osascript	trash-empty	same	same
iCloud	brctl evict	skip	skip	skip
OrbStack reset	orb delete	skip	skip	skip

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
• [ -d ~/.cache/kilter ]
• command -v xcrun

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