cleanMyMacSkill
Read-only storage analyzer for macOS, Windows, and Linux. Produces an interactive, Apple-style web-based dashboard with safe one-click cleanup integrations.
Core Directives
- Read-Only Scanner. The scanning phase only uses safe operations (e.g.,
df,du,stat,ls). Direct modifications or deletions are strictly prohibited during scanning. - Interactive Deletions. In server mode, users can click "Move to Trash" or "Hard Delete" on the web page. The backend validates paths against strict session tokens and home boundaries.
- Accurate Estimates. Explicitly mark any reclaimable space values as estimates.
- Retain Command Snippets. Keep absolute paths and terminal command snippets exactly as they are (do not translate paths).
Execution Pipeline
Step 1: Run Storage Scan
Execute the multi-threaded scan script to collect filesystem size metadata:
python3 scripts/scan.py > /tmp/storage_scan.json
The script detects the OS automatically and concurrently queries cache targets, user folders, and developer structures using standard ThreadPoolExecutor. Denied folders are marked as denied.
Step 2: Interpret & Segment
Read /tmp/storage_scan.json. Load references at references/macos.md, references/windows.md, or references/linux.md depending on the OS platform. Perform the following checks:
- Identify Top 5 Space Consumers: Mark their types (User files, databases, developer caches, VM files, etc.).
- Track App Sandbox Folders: Correlate UUID folders in containers back to their parent bundle-id names.
- Partition into Clean Tiers:
- 🟢 Safe to Clean: Caches, logs, package registers. Offer one-click trashing or direct deletions.
- 🟡 Needs Review: Personal documents, downloads, active database container folders. Enable opening in the file manager or trashing verified safe subfolders.
- 🔴 Caution: Software application packages. Guide users to uninstall manually via official settings.
Step 3: Compile and Serve Report
Inject the interpreted classification JSON into the template. Use the server script for interactive dashboard functionality:
python3 scripts/server.py /tmp/storage_analysis.json
Alternatively, compile a static HTML file:
python3 scripts/build_report.py /tmp/storage_analysis.json ~/Desktop/cleanmymac-report.html
Step 4: Dialogue Summary
Once generated, output a concise summary in the chat:
- Total space scanned and free space remaining.
- Estimated reclaimable capacity.
- Top 2-3 cleanup priorities and potential risks.
Platform Prerequisites
- Runs on Python 3 Standard Library (no pip dependencies).
- Compatible with macOS, Linux (Freedesktop compliant trashing), and Windows.