---
name: storage-analyzer
description: Read-only storage analysis for macOS and Windows. Finds the biggest disk hogs, classifies them, and generates an interactive cleanup report.
---

# Storage Analyzer

Run a read-only storage analysis and produce an interactive HTML report.

## Hard rules

- Read-only only. No deletion, moving, trashing, permission changes, or cleanup commands should actually run.
- Cleanup commands may be shown to the user, but only as copyable guidance.
- Mark all release-space figures as estimates.
- Do not translate paths or commands.

## Workflow

1. Scan the machine and write results to `/tmp/storage_scan.json`.
2. Analyze the top space users.
3. Classify them into:
   - Green: safe to clean automatically
   - Yellow: needs human judgment
   - Red: should not be deleted manually
4. Build an interactive HTML report.
5. Optionally run the local report server for one-click browser actions.

## What to look for

- Large caches
- Application data
- Downloads
- User files
- VM images
- Mystery UUID containers
- Anything taking unusually large space

## Output requirements

- Give the estimated space that can be freed.
- List the processes to close before cleanup when relevant.
- For each green item, provide a safe cleanup command or app-specific cleanup path.
- For each yellow item, explain the content, the risk, and the best cleanup route.
- For each red item, explain why it should not be removed manually and suggest a proper uninstall path.

## Report

The report should show:

1. Disk overview
2. Top offenders
3. Cleanup advice
4. Expandable green/yellow/red cards
5. Long-term optimization ideas

## Platform notes

- macOS is fully supported and tested.
- Windows support is implemented, but should be checked carefully on first run.

## Long-term tips

- Use `brew cleanup`
- Clear browser caches
- Clean Xcode DerivedData
- Move large archives to external storage, iCloud, or NAS
