# Clean Caches

> Reclaim disk space by cleaning macOS/Linux dev caches (Docker/OrbStack, package managers, Xcode, Homebrew, 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.

- Skill: `usrrname/clean-caches` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add usrrname/clean-caches`
- Raw SKILL.md: https://api.skillmd.com/api/skills/usrrname/clean-caches/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: usrrname (https://skillmd.com/u/usrrname)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/usrrname/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:

```bash
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](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.