storage-analyzer

Original：🇨🇳 Chinese
Translated
3 scriptsChecked / no sensitive code detected

Read-only Storage Analysis Assistant for macOS / Windows (auto-detects system). Scans the entire disk usage to identify space hogs, categorizes each item into three levels: 🟢 Auto-cleanable / 🟡 Manual judgment required / 🔴 Clean with caution, and provides actionable disposal plans. Generates an interactive HTML report with beautiful formatting, collapsible sections, and one-click copy commands. Also supports starting a local service to delete files directly via the web (move to trash / delete immediately). The entire scanning process is read-only. Must be used in the following scenarios: When users mention "storage analysis", "disk full", "C drive/hard disk full", "insufficient space", "clean up space", "disk cleanup", "space occupied", "what's taking up space", "help me check storage", "check computer storage/space", "storage space", "computer space insufficient", "memory full/insufficient" (in Chinese colloquial, "memory" often refers to storage), "storage analysis", "disk cleanup", "clear cache", "disk cleanup"; or when users complain about insufficient computer space, want to know what's taking up hard disk space, or need cleanup suggestions. Note: If users explicitly refer to RAM (e.g., "which process is using memory", "high memory usage", want to see Activity Monitor), that's RAM, not storage, and does not belong to this skill.

5installs
Sourcekkkkhazix/khazix-skills
Added on

NPX Install

npx skill4agent add kkkkhazix/khazix-skills storage-analyzer

Tags

Translated version includes tags in frontmatter
storage-analysisdisk-cleanuphtml-reportcross-platformpython-script

SKILL.md Content (Chinese)

View Translation Comparison →

Storage Analyzer

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

Iron Rules

  • Read-only throughout. Only run scanning/statistics/directory listing/metadata reading (df, du, diskutil, stat, ls). Strictly prohibit any write operations such as rm, mv, rmdir, emptying the recycle bin, changing permissions, etc.
  • Only display deletion commands, do not execute them. The cleanup commands provided in the report are for users to run in the terminal after confirmation. Even if the user says "help me delete" in the conversation, stop to confirm first (hit global red line: must ask before deleting files), do not run the command directly.
  • Clearly mark estimates. Always indicate that "releasable space" is an estimated value.
  • Keep paths and commands in original language without translation.

Execution Process

Step 1 Scan (Read-only)

bash
python3 scripts/scan.py > /tmp/storage_scan.json
scan.py
automatically detects the system (
sys.platform
):
  • macOS: Scans home, library, caches, containers, group_containers, app_support, applications, downloads, dev_caches, calculates sizes using 
    du
    .
  • Windows: Scans user_profile, appdata_local, appdata_roaming, temp, downloads, program_files(_x86), dev_caches, calculates sizes using 
    os.scandir
    ; 
    system.disks
    includes all drive letters.
Output JSON: 
system
(system/disk information, including 
disk_name
main disk name + 
disks
all disks) + 
groups
(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 
denied
, and the missed volume should be listed in the report with a prompt.

Step 2 Analysis and Categorization

First, determine the system using 
system.os
, 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 
/tmp/storage_scan.json
to do the following:
  1. Select Top 5 space hogs, determine their types (system assets, application installations, application data, application caches, development caches, user files, media content, downloaded content, virtual machine images, recycle bin, others).
  2. Identify "mysterious large directories": UUID-named Containers, unknown hidden directories. Trace which App they belong to and what they contain (e.g., a 97GB UUID Container is actually Bilibili offline video cache). If necessary, use 
    ls
    /
    du
    to look one level deeper, but remain read-only.
  3. Three-level classification = cleanup decision list, not a full inventory. Only include items that require a "should I move it" decision in the three-color categories. Regular daily applications, the operating system itself, and massive small files without cleanup decisions are not included in the three-color categories; they fall into the blue "System and Others" section of the disk bar. Judgment criteria:
    • 🟢 Auto-cleanable: Pure cache, temporary files, installation package residues, clearly regenerable without affecting functionality or losing user data (development caches like pip/uv/npm/Xcode DerivedData, browser caches).
    • 🟡 Manual judgment required: Contains user data or requires judgment (offline videos, documents, project code node_modules, chat records, design drafts). Provide content profiling + at least 3 disposal paths (in-app cleanup / system tools / manual review via file manager, choose the most suitable three) + risk warnings. All yellow items automatically have an "Open in Finder/File Explorer" button in service mode (jump to review and delete manually); if the item has a verified safe subpath that can be deleted without damaging the App (e.g., 
      .Downloads
      directory for Bilibili offline videos, old backup directories), assign it 
      trash_paths
      → a "Move to Trash" button appears on the webpage (yellow items can only be moved to trash, reversible, never allow "direct deletion"). Apps hosted without safe subpaths (Chrome/WeChat) only provide an open button, no 
      trash_paths
      . Notes are automatically displayed below the buttons (open only for viewing not deletion, moving to trash is reversible and requires emptying to release space, etc.); if an item is in an App-internal format that is inconvenient to manually select in the file manager, add an 
      open_note
      field for objective explanation (will be displayed in the notes). Tone should be neutral, like product instructions: Directly describe "what structure this is, why it's not easy to delete manually, where to go for fine-grained operations", do not write from a developer's perspective like "I found/remind you/it looks like no videos".
    • 🔴 Clean with caution (decision needed but not recommended to delete manually): Specific items you might want to move but are advised not to delete manually—duplicate applications, large apps you want to uninstall, core data of running apps, etc. Provide "why manual deletion is not recommended" + 
      indirect_release
      with specific uninstall steps (built-in uninstaller / long press in Launchpad / right-click to move to trash / AppCleaner to clear residues / reinstall via App Store, etc., must be actionable not empty words). For app items, assign 
      app_paths
      (array of real 
      .app
      absolute paths) → an "Open in File Manager (to uninstall)" button appears on the webpage, locating the App for users to uninstall formally. Red items do not have delete/uninstall buttons (apps are in system directories, may require administrator password, may have built-in uninstallers and residues, background deletion is unstable). Pure system files, APFS snapshots should not be listed separately as red cards (no cleanup decision), they belong to the blue section; system-level release techniques (restart to release swap, Time Machine snapshot strategy, automatic recovery of freeable space) are written into 
      summary.long_term
      long-term suggestions.
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 
rm
cautiously; if using 
rm
, it must be a clear cache subdirectory).
Keep size fields clean: 
size
/ 
size_estimate
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.

Step 3 Generate Interactive Report

Write the analysis results into an analysis JSON (schema see top comments of 
scripts/build_report.py
).
🟢 items must include 
trash_paths
 (array of specific deletable absolute paths, different from the human-readable 
path
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:
bash
python3 scripts/server.py /tmp/storage_analysis.json   # Automatically opens browser, Ctrl+C to stop
server.py
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: 
rm
only allows green 
trash_paths
; 
trash
allows green + yellow 
trash_paths
(yellow items can never use rm); 
open
(open in file manager, non-destructive) allows all of the above + yellow real 
path
. 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 
file://
cannot access the file system):
bash
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 
server.py
), or 
trash_paths
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 
summary.overview
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 
summary.priority
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 
summary.tier_stats
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.

Step 4 Provide Summary in Conversation

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.

Dependencies and Prerequisites

  • All scripts use Python 3 standard library, zero third-party dependencies (no need for pip install).
  • macOS comes with python3, 
    du
    , 
    diskutil
    , 
    osascript
    out of the box.
  • Windows does not have Python installed by default—need to install Python 3 first, and commands are often 
    python
    or 
    py -3
    (not 
    python3
    ). This skill uses 
    python3
    in command examples, which will automatically switch to 
    python
    / 
    py -3
    on Windows.
  • This skill is agent-driven: After scanning data, the agent (Claude) performs classification analysis, it is not a double-click-to-run independent App.

Platform Status

  • macOS: Fully implemented and tested (scanning / report / one-click deletion fully verified).
  • Windows: Code is written (
    scan_windows
    in 
    scan.py
    , 
    _trash_windows
    in 
    server.py
    uses 
    SHFileOperationW
    ), but not tested on real Windows. When running on Windows for the first time, verify: target directory paths, 
    os.scandir
    size, recycle bin deletion functionality. Multi-drive support is already implemented (main disk progress bar + other disk list).

Long-term Optimization Suggestions Material (write into report summary.long_term)

  • Regular cleanup: 
    brew cleanup
    , Xcode DerivedData, browser caches
  • Visualization tools: DaisyDisk, GrandPerspective, OmniDiskSweeper
  • Archive large files to external drive / iCloud / NAS; macOS "System Settings > General > Storage" optimization options