Agent-Skills.md

Agent Skills: macOS Disk Housekeeping

Use when macOS disk space is low, "disk full", 硬碟空間不夠, startup disk almost full, or before installing something large — diagnoses what is eating space and reclaims it safely

UncategorizedID: htlin222/dotfiles/housekeeping

Repository

htlin222/dotfiles
htlin222License: MIT
784

Install this agent skill to your local

pnpm dlx add-skill https://github.com/htlin222/dotfiles/tree/HEAD/.claude/skills/housekeeping

Skill Files

Browse the full folder contents for housekeeping.

Download Skill

Loading file tree…

.claude/skills/housekeeping/SKILL.md

Skill Metadata

Name
housekeeping
Description
Use when macOS disk space is low, "disk full", 硬碟空間不夠, startup disk almost full, or before installing something large — diagnoses what is eating space and reclaims it safely

macOS Disk Housekeeping

Overview

Diagnose → reclaim safe targets → verify. Known-safe cleanup only; never touch personal data. reference/prune.sh automates the whole flow (dry-run by default).

Diagnosis

df -h /System/Volumes/Data        # the REAL usage (df / shows the sealed system snapshot)
du -sh ~/Library/* | sort -rh | head        # usual suspects
du -sh ~/* ~/.[a-z]* 2>/dev/null | sort -rh | head
tmutil listlocalsnapshots /       # MSUPrepareUpdate = staged macOS update

Known hogs on this machine (2026-07 findings)

| Target | Typical size | Action | |---|---|---| | ~/Library/Application Support/Claude/vm_bundles | ~10G | delete if VM not running (pgrep -fl claudevm); rebuilds on demand | | ~/Library/pnpm store | 7G+ | pnpm store prune | | ~/Library/Caches/{com.spotify.client,BraveSoftware,Google,com.brave.Browser,pip,go-build,node-gyp} | ~4G | delete outright | | ~/.cache/uv | 2G+ | uv cache prune (remainder is referenced by live venvs — leave it) | | /opt/homebrew | 20G+ | brew cleanup --prune=all && brew autoremove | | MSUPrepareUpdate snapshot | few GB | finish the pending macOS update (reboot) — softwareupdate -l to see it |

Do NOT delete

  • ~/Library/Caches/ms-playwright* — breaks E2E until playwright install
  • ~/.cache/codex-runtimes — Codex plugin runtime
  • ~/Pictures, ~/Library/Group Containers, Mail — personal data
  • leftover ~/.cache/uv after prune — hardlinked into venvs

Gotchas

  • rip does not free space. It moves files to /tmp/graveyard-$USER on the same volume. After ripping large targets run yes | rip --decompose and re-check df.
  • brew cleanup frees nothing when packages are outdated — it only deletes versions older than the installed-latest. Upgrade first if you want real savings.
  • uv cache prune vs clean: prune keeps in-use entries (correct); clean wipes all (pointless — hardlinked files free nothing).

Automation

reference/prune.sh          # dry-run report of known-safe targets
reference/prune.sh --apply  # actually clean them

# Find NEW candidates: large + old + cold, ranked by "storage rent"
# (score = size_GB × idle_days; gates on created>180d AND atime>90d;
#  top hits cross-checked with Spotlight kMDItemLastUsedDate)
reference/clean-large-and-olds.sh                       # scan $HOME, top 20
reference/clean-large-and-olds.sh --root DIR --min-size 50 --top 30

clean-large-and-olds.sh is report-only — review, then rip <paths> + yes | rip --decompose.