system.analyze_disk_space_use

Goal

• Find what is consuming the most disk space, identify what is safely reclaimable (unused container/VM images, caches, logs) versus what needs manual review, and report the findings
• Never delete, move, or modify anything: analysis only

Workflow

Check Overall Disk Usage

• Run df -h to see total/used/available space per volume
• On macOS, the volume that actually holds user data is /System/Volumes/Data, not /: use its Capacity/Avail columns to judge how urgent the situation is

Survey the Home Directory

• List top-level home directory usage, largest first:

  > du -sh ~/* 2>/dev/null | sort -rh
  

• Recurse one level at a time into whichever directory dominates (on macOS this is typically ~/Library), always sorting by size, until you reach the actual large items instead of just a big parent directory name:

  > /usr/bin/du -sh ~/Library/* 2>/dev/null | sort -rh | head -30
  

• Track every directory measured along the way: it feeds the top-10 list in "Rank Findings And Write The Report"

Check Container and VM Engines First

• On a dev machine these are usually the single biggest consumer, because they cache every pulled/built image and rarely self-prune
• For every engine that is installed, check its own usage report before digging into raw directory sizes:
  • Docker: if docker exists, run docker system df -v for a per-image/per-volume breakdown; images with CONTAINERS = 0 are unused and reclaimable
  • Apple container CLI (native macOS containers): if container exists, run container system df; its data lives under ~/Library/Application Support/com.apple.container and Docker's VM disk lives under ~/Library/Containers/com.docker.docker
  • Other engines present (podman, colima, lima, nerdctl): use their equivalent system df / usage-report command
• A builder container (e.g. Docker's buildx state volume, Apple's buildkit builder container) can be reported as "active" and excluded from RECLAIMABLE by the tool even when it has grown very large
  • Size it directly with /usr/bin/du -sh <PATH> and report it as a manual candidate, along with the reset command that would reclaim it (docker buildx prune --all, or container builder stop && container builder delete)