dennisonbertram/claude-mac-guardian/disk-usage

disk-usage

Surveys storage usage on macOS without deleting anything.

When to invoke

Trigger on phrases like: "check disk usage", "is my drive full", "what's using my disk", "disk space", "free up space".

What to check

1. Per-volume free space — df -h. Filter to apfs and hfs volumes. For each volume:

• / free ≥ 20 GB or ≥ 15%: ok.
• / free 10–20 GB or 5–15%: info.
• / free 5–10 GB or 2–5%: warn.
• / free < 5 GB or < 2%: critical.

2. Top 20 home directories by size — du -shx ~/* 2>/dev/null | sort -rh | head -20. Record as raw. Individual dirs ≥ 50 GB get an info finding.

3. Library caches — du -shx ~/Library/Caches 2>/dev/null. If ≥ 20 GB, info "Library caches at <size>".

4. System / user log sizes — du -shx ~/Library/Logs /private/var/log 2>/dev/null. Record in raw.

5. Time Machine local snapshots — tmutil listlocalsnapshots / 2>/dev/null. Report the count. ≥ 10 snapshots: info.

6. Xcode / iOS simulator footprint — du -shx ~/Library/Developer/CoreSimulator/Devices ~/Library/Developer/Xcode/DerivedData ~/Library/Developer/Xcode/iOS\ DeviceSupport 2>/dev/null. Sum ≥ 30 GB: info. Sum ≥ 100 GB: warn.

7. node_modules across common dev roots (optional and guarded) — only run when the user's home has a Develop/ or Projects/ or code/ directory: find ~/Develop ~/Projects ~/code -type d -name node_modules -maxdepth 6 -prune -exec du -shx {} + 2>/dev/null | sort -rh | head -20. Guard this with a soft timeout (use timeout 60s if gtimeout or coreutils timeout is available; otherwise include only if find completes within reason, and skip with an info finding "skipped — search would take too long" if not).

8. Large Downloads / Trash — du -shx ~/Downloads ~/.Trash 2>/dev/null. Each ≥ 10 GB: info.

Output contract

Standard envelope. Write to ~/.mac-guardian/data/disk-usage-<ISOdate>.json.

Top-level severity = max across all checks. Summary example: "44 GB free on / (warn). Biggest: ~/Library/Caches 38 GB, DerivedData 27 GB."

Handoff

• On direct invocation: bash ${CLAUDE_PLUGIN_ROOT}/scripts/render-single.sh disk-usage.
• When invoked by daily-health-report, return JSON path only.

Safety

• Read-only. Never delete caches, snapshots, DerivedData, or node_modules.
• If the user asks to clean up after seeing the report, explain what the commands would be and prompt for confirmation.
• Do not call sudo.