system.analyze_disk_space_use

Goal

• Find what consumes the most disk space. Identify what is safely reclaimable (unused container/VM images, caches, logs) and what needs manual review
• Never delete, move, or modify anything. Analysis only

Workflow

Check Overall Disk Usage

• Run df -h to see total, used, and available space per volume
• On macOS, user data lives on /System/Volumes/Data, not /. Use its Capacity/Avail columns to judge urgency

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 the dominant directory (on macOS, often ~/Library), sorting by size, until you reach the actual large items:

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

• Track every directory measured. They feed the top-10 list in "Rank Findings And Write The Report"

Check Container and VM Engines First

• Container and VM engines are usually the biggest consumer on a dev machine. They cache every pulled or built image and rarely self-prune
• For each installed engine, check its usage report before raw directory sizes:
  • Docker: if docker exists, run docker system df -v for a per-image and 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. Docker's VM disk lives under ~/Library/Containers/com.docker.docker
  • Other engines (podman, colima, lima, nerdctl): use their equivalent system df / usage-report command
• The tool can report a builder container (Docker buildx state volume, Apple buildkit builder) as "active", which excludes it from RECLAIMABLE even when it is very large
  • Size it with /usr/bin/du -sh <PATH>. Report it as a manual candidate, with the reset command (docker buildx prune --all, or container builder stop && container builder delete)