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.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
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.
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 snapshots, or CoW clones)
launchservicesd DB bloat specifically โ see launchservices-health
Deleting a big tree freed far less than du promised
โ
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.
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.
The third fact: du also over-counts in the other direction โ copy-on-write clones. APFS reports a cloned file at fullst_blocks even though its blocks are shared and cost nothing, so a du total can far exceed what deleting the tree would actually free. This is not fixable by switching tools: dust, gdu, and ncdu all read st_blocks and double-count identically. See CoW clones below.
Step 1: Measure honestly (built-in CLI)
# Trust Avail, NOT Capacity % โ APFS shares free space container-widedf -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 -hx -d1 / 2>/dev/null | sort -h
du -hx -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 for sparse files โ but not as a general rule: allocated blocks are also what makes du over-count clones (below), and they never include purgeable snapshot space.
CoW clones: du over-counts what deleting would free
A copy-on-write clone (cp -c, clonefile(2)) shares blocks with its source, so it costs ~nothing โ but every tool reading st_blocks bills it at full size. Measured on a 200 MB file plus one clone (ground truth: 200 MB):
Tool
Reports
BSD du, GNU du, dust, gdu
400M
dust -s (apparent)
600M โ also counts hardlinks
df delta
0 MB for the clone โ
All of them dedupe hardlinks by inode; a clone has a distinct inode, so that logic never fires.
This is not academic โ it is the default on this platform for two common package managers:
Tool
Global cache
2nd project's copy costs
du claims
uv โ .venv
~/.cache/uv
0 bytes (clonefile)
full size
bun โ node_modules
~/.bun/install/cache
0 bytes (clonefile)
full size
cargo โ target/
~/.cargo/registry (sources only)
full size โ each project compiles its own copy
accurate
So du is honest for target/ and inflated for node_modules/.venv. Deleting a clone frees real space only where it holds the last reference to those blocks.
When a size gates a decision ("how much will this free?"), measure a df delta โ it is the only clone-aware measurement available:
Real cost of skipping this: a reclaim sweep summing du predicted 68.7 GB where the df delta was 17.7 GB โ a 4ร overstatement (2026-08). Clones are detectable via fcntl(F_LOG2PHYS_EXT) โ a clone shares physical device offsets while having a distinct inode, and stat/MetadataExt carries no clone signal at all โ but no general-purpose tool implements it yet (bootandy/dust#590).
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 sudosudo tmutil thinlocalsnapshots / 999999999999 4
Step 1.5: Fast-path โ the usual-suspects scan
Step 1 gives the honest total; this gives where it went without re-deriving the hunt by hand each time. scripts/scan-suspects.sh reads a public catalog of known reclaim targets (scripts/suspects.tsv โ dev caches, build-artifact dirs, VM images), dus the ones that exist on this machine, and emits a ranked rollup with the cleanup command and safety tier already attached:
# Whole home (thorough; slower โ du walks every tree)
bash "${CLAUDE_SKILL_DIR}/scripts/scan-suspects.sh" --home-dir "$HOME" --root "$HOME"# Bound the build-artifact search to where projects live, raise the noise floor
bash "${CLAUDE_SKILL_DIR}/scripts/scan-suspects.sh" --root ~/repos --min-mb 1000
Output follows the structured SUSPECT id=โฆ tier=โฆ size_kb=โฆ cmd="โฆ" convention, plus a ranked human table and per-tier totals (TIER_SAFE_KB=โฆ, RECLAIMABLE_SAFE=โฆ). Work the tiers exactly as Step 4 โ exhaust safe before decision, never blind-delete userdata.
โ ๏ธ Those totals are du sums, so they are an upper bound wherever CoW clones apply โ notably the node_modules / .venv suspects, which uv and bun clone from a global cache. Treat RECLAIMABLE_* as "at most this much"; confirm with a df delta after acting. See CoW clones.
This augments Step 1, it does not replace it. The scan is pure measurement; the judgment stays with the agent โ reading the APFS Avail-not-Capacity % picture, checking purgeable snapshots when du and df disagree, and deciding whichdecision/userdata items to actually remove.
The UNKNOWN lines are the feedback loop. Any big directory not in the catalog is surfaced as UNKNOWN size_kb=โฆ path=โฆ. When one recurs, add it to suspects.tsvas a pattern (never a machine-specific path โ this repo is public) and open a PR; the catalog grows from real findings. Catalog columns and placeholders ({dir}, {parent}) are documented in the file's header.
Two operational notes:
Runtime scales with disk size โ du walks every tree, so a full disk can take a minute or two. Bound with --root <project-dir> and --min-mb; swap in dust (Step 3) if you want the walk parallelised.
The catalog is the shared artifact; the scan output is machine-specific โ keep it in scratch, never commit it.
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, -j JSON to stdout
