Perform a read-only storage analysis on macOS and generate an interactive HTML report. Process: Scan → Analyze and categorize → Generate webpage → Open.

python3 scripts/scan.py > /tmp/storage_scan.json

automatically detects the system ():

Output JSON: (system/disk information, including main disk name + all disks) + (subdirectory sizes of each group, sorted in descending order, filtered to exclude items below 50MB). Scanning is slow, please be patient. Directories that cannot be read are marked , and the missed volume should be listed in the report with a prompt.

First, determine the system using , and read the corresponding data layout reference: for macOS, read references/macos.md, for Windows, read references/windows.md (explains where things are stored in the system, how to identify them, and which category they belong to). Then read to do the following:

Each 🟢 item must include: estimated releasable space, processes to close before cleanup, one-click copyable cleanup commands (use safe methods like moving to trash or App's own cleanup entry, use cautiously; if using , it must be a clear cache subdirectory).

Keep size fields clean: / should be written as "~14 GB" "total 8.6 GB"—the "" already indicates an estimate, do not add "(estimated)" which is redundant and unprofessional (the template will automatically remove such redundant parentheses). The regenerable attribute is covered by the category title and button descriptions, do not include it in the size field.

Write the analysis results into an analysis JSON (schema see top comments of ).

🟢 items must include

trash_paths

(array of specific deletable absolute paths, different from the human-readable display field)—this is the prerequisite for the webpage delete button; if missing, the button will not appear.

By default, open the report in one-click delete mode (

server.py

), because the core value of this skill is direct cleanup via the webpage:

python3 scripts/server.py /tmp/storage_analysis.json   # Automatically opens browser, Ctrl+C to stop

runs on 127.0.0.1 + random port + random token. 🟢 items have "Move to Trash" (reversible) + "Delete Immediately" (immediate release, irreversible); 🟡 items have "Open in Finder" + (if there is a safe subpath) "Move to Trash". Security model—three sets of whitelists, permissions from strict to loose: only allows green ; allows green + yellow (yellow items can never use rm); (open in file manager, non-destructive) allows all of the above + yellow real . All requests are validated with realpath + must be within $HOME + token + Host validation, and the browser confirms before each click. osascript/SHFileOperationW is used to move to trash; for macOS, allow the first Finder automation authorization prompt.

Only when the user explicitly wants a shareable/savable read-only file, use static mode (no delete buttons, because pages opened via cannot access the file system):

python3 scripts/build_report.py /tmp/storage_analysis.json ~/Desktop/storage-report.html && open ~/Desktop/storage-report.html

Troubleshooting: No delete/move to trash buttons on the webpage = either the static report is opened (switch to ), or is missing for 🟢 items (add it and restart the service).

Report reading flow (fixed order): Disk overview card (capacity + progress bar + three-color capacity pills + system information, pure data) → Top5 space usage ranking → Execution suggestions → 🟢🟡🔴 collapsible three-level cards (one-click copy commands) → Long-term optimization suggestions. That is "Current Status → Diagnosis → Prescription → Operation → Prevention".

Note that should be written as a one-sentence insight (directly state what the largest space usage is and how much can be released), do not repeat total/used/available numbers—those are already displayed in the large numbers of the card. The overview is rendered as an introduction in plain text at the beginning of the "Execution Suggestions" section, followed by the priority list.

The disk progress bar splits "used" into segments: green (auto-cleanable) + orange (manual required) + red (identified items not recommended to move) + blue (system and others, automatically calculated as used - green - orange - red), with the remaining space as available (gray background). The green / yellow / red values in must start with parsable GB numbers (e.g., "~27.8 GB"), and the script extracts numbers from them to calculate segments; the blue segment and "System and Others" pill are automatically calculated by the template using the remaining amount.

Pills only render parsed pure numbers (e.g., "~5.5 GB"), do not display notes in the data, so the three values in tier_stats should be clean numbers, do not add apologetic notes like "only identified items/system not included"—system files are already in the blue section, red only includes quantifiable 🔴 items (duplicate apps, large apps to uninstall, etc.), system files/snapshots with inaccurate volume naturally fall into the blue section.

After generating the report, provide a conclusion-first summary in the conversation: estimated total releasable space, 2-3 top priority items to clean up, and the highest-risk item. Let users check the webpage for details.