macos-disk-usage

name	macos-disk-usage
description	macOS disk-usage forensics and space recovery on APFS. Use when df reports a disk near-full, hunting what's eating space, reclaiming OrbStack/Docker, or pruning caches and local snapshots.
user-invocable	false
allowed-tools	Bash(uname *), Bash(df *), Bash(du *), Bash(diskutil *), Bash(tmutil *), Bash(docker *), Bash(brew *), Bash(go *), Bash(pip *), Bash(uv *), Bash(dust *), Bash(dua *), Bash(gdu *), Bash(ncdu *), Bash(mise *), Read, Grep, Glob, TodoWrite
created	"2026-06-21T00:00:00.000Z"
modified	"2026-06-21T00:00:00.000Z"
reviewed	"2026-06-21T00:00:00.000Z"

macOS Disk Usage & Space Recovery

When to Use This Skill

Use this skill when...	Use something else when...
df reports a volume near-full and you need the honest figure	The root disk on Linux is full — use the Linux-focused disk-full-recovery rule
Hunting "what's eating my disk" on macOS	General process forensics — use ps/top directly
Reclaiming space from OrbStack/Docker, caches, or local snapshots	A GUI hang/freeze occurred — see macos-incident-postmortem
du totals and free space disagree (purgeable snapshot space)	launchservicesd DB bloat specifically — see launchservices-health

Platform Guard

This skill is macOS-only. APFS containers, diskutil apfs, tmutil local snapshots, and BSD du block-counting are Darwin-specific. Refuse to act if uname -s is not Darwin.

test "$(uname -s)" = "Darwin" || { echo "macos-plugin: not Darwin, refusing"; exit 1; }

This skill cross-references, does not duplicate, the Linux-focused disk-full-recovery rule (root partition, ~/.cache, apt/journalctl). The APFS / Time Machine / OrbStack angle below is the macOS-specific complement.

Core Expertise

The single most-important macOS fact: APFS shares free space across every volume in a container. A per-volume Capacity % is therefore misleading — the sealed system snapshot volume routinely reads 99% while the container has tens of GB free. Trust the Avail column (or diskutil apfs list), never the Capacity %, or the investigation goes down the wrong path before it starts.

The second fact: du lies about reclaimable space. tmutil local snapshots hold purgeable space that du never counts, so du totals and reported free space can disagree by tens of GB. Check snapshots first when the numbers don't reconcile.

Step 1: Measure honestly (built-in CLI)

# Trust Avail, NOT Capacity % — APFS shares free space container-wide
df -h /

# The container's real free space, per-volume roles, and snapshot count
diskutil apfs list

# Top-level consumers, one level deep, staying on one filesystem (-x)
du -shx -d1 / 2>/dev/null | sort -h
du -shx -d1 ~ 2>/dev/null | sort -h

BSD du counts allocated blocks, so it reports the real on-disk size of sparse files (e.g. OrbStack's data.img.raw reads its true 33 GB, not its apparent size). Trust the number.

Purgeable snapshot space (the thing du hides)

When du totals and df free space disagree, local Time Machine snapshots are the usual cause:

# List local snapshots holding purgeable space
tmutil listlocalsnapshots /

# Thin them (reclaims purgeable space invisible to du); needs sudo
sudo tmutil thinlocalsnapshots / 999999999999 4

Step 2: The OrbStack / Docker recovery play

OrbStack/Docker is frequently the dominant consumer (100+ GB seen). The VM image (data.img.raw) grows but never shrinks on its own. The recovery is: prune inside the VM, then OrbStack auto-shrinks the host image (unlike Docker Desktop, which needs manual reclaim).

# See what's reclaimable before pruning
docker system df

# Prune unused images + build cache (NOT volumes — see warning below)
docker system prune -a -f

A real session reclaimed 85 GB this way (159 images / 57 GB reclaimable, 42 GB build cache), after which OrbStack auto-shrank the host image 103 GB → 33 GB.

Never blind-prune named volumes

docker volume ls -f dangling=true lists named volumes (olmap_postgres_data, docker_neo4j_data, …) that are "unused" only because no container is currently running — they hold live project databases. A blind docker volume prune would wipe them.

# Inspect first — named volumes are project data, anonymous-hash ones are scratch
docker volume ls -f dangling=true

Prune only anonymous-hash volumes (long hex names), never the human-named ones, and only after confirming with the user.

Step 3: Third-party tooling

Install via the mise aqua: backend (checksum-verified standalone binaries):

mise use -g aqua:bootandy/dust   # `dust` — fast tree-map, the one to lead with
mise use -g aqua:Byron/dua-cli   # `dua`  — interactive TUI via `dua i`

Tool	Install	Strength
dust	aqua:bootandy/dust	Fast visual tree; lead with this. dust -r reverse, -d N depth, -X <glob> exclude, -s apparent size
dua	aqua:Byron/dua-cli	Interactive deletion TUI (dua i)
gdu / ncdu	aqua:dundee/gdu, ncdu	TUI disk usage analyzers
diskonaut	aqua:imsnif/diskonaut	Spatial treemap navigator

GUI options (mention, don't install): DaisyDisk, GrandPerspective, OmniDiskSweeper.

Step 4: Tiered cleanup

Work top-down — exhaust the safe tier before touching anything that needs a decision.

Tier	What	How	Notes
Safe / regenerable	Homebrew downloads	brew cleanup -s	Rebuilds on next install
	Go module cache	go clean -modcache	Re-downloads on next build
	pip cache	pip cache purge
	uv cache	uv cache clean	Fails with a lock error if another uv process / active session is running
	Playwright / Yarn / node-gyp caches	rm -rf ~/Library/Caches/{ms-playwright,Yarn,node-gyp}	Regenerable
Needs a decision	Docker images + build cache	docker system prune -a -f	OrbStack auto-shrinks host image after
	Local Time Machine snapshots	sudo tmutil thinlocalsnapshots /	Loses local restore points
User data	Named Docker volumes	confirm each	Live project databases — never blind-prune
	Anything in ~/Documents, ~/Downloads	user confirms	Irreplaceable

Agentic Optimizations

Context	Command
Honest free space	df -h / | awk 'NR==2{print $4" avail"}'
Container free space	diskutil apfs list | grep -i 'Capacity In Use|Free'
Top home consumers	du -shx -d1 ~ 2>/dev/null | sort -h | tail -15
Snapshot count	tmutil listlocalsnapshots / | grep -c com.apple
Docker reclaimable	docker system df
Fast tree (dust)	dust -d2 -r ~

Quick Reference

Need	Command
Honest free space	df -h / (read Avail, not Capacity %)
APFS container truth	diskutil apfs list
Disk hog scan	du -shx -d1 <dir> or dust -d2 -r <dir>
Purgeable snapshots	tmutil listlocalsnapshots /
Thin snapshots	sudo tmutil thinlocalsnapshots / 999999999999 4
Docker reclaim	docker system df then docker system prune -a -f

Error Handling

Symptom	Cause	Fix
df shows 99% but space "missing"	APFS per-volume Capacity % on the sealed snapshot volume	Read Avail, or diskutil apfs list
du total ≪ used space	Purgeable local snapshots	tmutil listlocalsnapshots /; thin them
uv cache clean lock error	Another uv process / active session running	Close other uv work and retry
Docker image still huge after prune	Reclaim ran inside VM; host image not yet shrunk	OrbStack auto-shrinks shortly; Docker Desktop needs manual reclaim
volume prune wiped a database	Named volume pruned while no container ran	Restore from backup; only prune anonymous-hash volumes

Related Skills

• launchservices-health — when launchservicesd DB bloat (not disk usage) is the concern
• macos-incident-postmortem — when a freeze/panic, not a full disk, is the symptom
• disk-full-recovery (user-global rule) — the Linux-focused complement to this APFS-specific skill