cleanmymac

CleanMyMac

Architecture — discovery vs judgment vs action

Three separate layers. Never conflate them.

Layer	What it does	Script	Reversible?
DISCOVER	Tree-walks the filesystem from any path (default $HOME). For each immediate child, looks up the path against the judgment registry and annotates it. Like OmniDiskSweeper but with built-in classification.	diskmap.sh	N/A (read-only)
JUDGE	51 cleanup modules + a hardcoded never-touch list form the registry. For any path, it answers: is this auto-safe / needs-review / never-touch / unknown?	lib-registry.sh (consumed by diskmap & autoclean)	N/A
ACT	Deletes. Auto-safe runs in bulk. Review runs per-item interactively. Never-touch and unknown require explicit user opt-in.	autoclean.sh, execute.sh	Caches regenerate; review items are gone forever

Workflow

Phase 1 — Discover with diskmap (default)

~/.claude/skills/cleanmymac/scripts/diskmap.sh

Output: every folder ≥ 2 GB, auto-drilled to specific classifiable items, grouped into THREE tiers (no "unknown" — diskmap auto-classifies via registry + heuristics):

Icon	Tier	Meaning
✅	auto_safe	Cache / build artifact (registry match OR cache-name heuristic). Deletable in bulk with no impact.
⚠️	review	Anything else (app data, sandboxed app, AI model weights, backups). Decide per-item.
🔒	never_touch	User data, OS files, iCloud, Mail, Messages, Keychain, SSH/GPG/AWS. Protected.

To drill into a specific path:

diskmap.sh <path>          # e.g. diskmap.sh ~/Library
diskmap.sh / --top 20      # full-disk view (some TCC denials expected)
diskmap.sh --threshold 500M  # surface anything ≥ 500 MB
diskmap.sh --json          # JSON output for parsing

⚠️ MANDATORY OUTPUT RULE — paste diskmap verbatim

When presenting scan results to the user, you MUST paste the diskmap output VERBATIM inside a single fenced code block (text … ). Do not:

• ❌ Reformat into markdown tables
• ❌ Split items into your own sub-categories ("AI 类 / 应用类 / 开发类")
• ❌ Drop columns, drop rows, or change column order
• ❌ Add your own emoji/colors/icons on top of what diskmap already prints
• ❌ Truncate paths or rename modules

The diskmap output IS the canonical UI. It is fixed-width text with three sections (✅ AUTO-SAFE / ⚠️ NEEDS REVIEW / 🔒 NEVER-TOUCH), one item per line, format SIZE | WHAT IT IS | WHERE. Users specifically asked for this layout — preserve it byte-for-byte.

After the code block, you MAY add at most ONE short sentence recommending the next step (e.g. "建议先清 27.7 GB 安全项 → autoclean.sh --auto-safe --yes"). Nothing more elaborate than that.

Phase 2 — Act with autoclean

After the user understands the landscape, ask which mode:

~/.claude/skills/cleanmymac/scripts/autoclean.sh                          # scan modules + show 3-tier breakdown
~/.claude/skills/cleanmymac/scripts/autoclean.sh --auto-safe --yes        # delete auto-safe in bulk (recommended)
~/.claude/skills/cleanmymac/scripts/autoclean.sh --review                 # interactive per-item for medium/high
~/.claude/skills/cleanmymac/scripts/autoclean.sh --all                    # both

The --review mode walks the user through each medium/high-risk module: shows name + size + what-it-is + what-happens-if-deleted, then prompts [d]elete / [k]eep / [q]uit.

Phase 3 — Drill into unknowns (optional)

If diskmap shows large ❓ unknown folders, suggest drilling:

diskmap.sh ~/.cursor       # for example, if .cursor was big and unclassified
diskmap.sh ~/Library/Containers

For folders that turn out to be safe regenerable data (e.g. a new AI tool's cache), suggest adding a module to the registry — open a PR with src/modules/<name>.sh + whitelist entry.

Phase 4 — Smart Advisor (optional, complementary)

advisor.sh runs 9 specific heuristics for things diskmap can't auto-classify by path alone (e.g. old node_modules in any project, stale conda envs, downloaded chat media). Use it when diskmap surfaces unknown folders that match these patterns.

~/.claude/skills/cleanmymac/scripts/advisor.sh --interactive

Phase 5 — Schedule (optional)

Ask: "Want auto-cleanup to run weekly without you asking?"

~/.claude/skills/cleanmymac/scripts/schedule.sh

Interactive: pick cadence (weekly/biweekly/monthly/custom) and scope. Most users want weekly + safe-only.

Phase 6 — Final report

• Bytes reclaimed (auto-safe + review combined)
• Items reviewed (kept vs deleted)
• Schedule status
• Largest unknowns the user did NOT drill into — list them, suggest module contributions

What you don't do

• ❌ Never delete an ❓ unknown path on the user's say-so without first showing them what it contains (drill into it)
• ❌ Never delete anything in the review tier without explicit per-item OK
• ❌ Never run rm -rf directly — all deletes go through safe_rm (whitelist-gated)
• ❌ Never bypass the whitelist for any reason
• ❌ Never sudo without --with-sudo consent
• ❌ Never docker volume prune (banned at build time)
• ❌ Never touch the 🔒 never_touch list: ~/Documents, ~/Desktop, ~/Pictures, ~/Movies, ~/Music, ~/Library/Mobile Documents (iCloud), ~/Library/Mail, ~/Library/Messages, ~/Library/Keychains, ~/.ssh, ~/.gnupg, ~/.aws
• ❌ Never touch browser Cookies, Login Data, History, Bookmarks, Preferences
• ❌ Never touch external/network volumes — only /
• ❌ Do not present medium/high-risk modules as "safe to delete" — they live in the REVIEW tier for a reason

Red flags to surface

1. 🚨 Unknown total >50 GB — there's a lot of unclassified data; drill in before any delete
2. 🚨 Single unknown folder >10 GB — almost always worth investigating (VMs, AI models, abandoned project deps)
3. 🚨 Single review item >5 GB — pause, double-check the user really wants it deleted
4. 🚨 Free space <5 GB after cleanup — suggest diskmap drill into ❓ unknowns
5. 🚨 Docker / Xcode running — docker prune skips running containers; DerivedData may be locked. Suggest quitting first
6. ⚠️ TCC permission denied on diskmap — show "true size ≥ X GB" line and tell user they can grant Full Disk Access in System Settings if they want true totals
7. ⚠️ Review tier includes iOS backups >5 GB — backups are NOT auto-recoverable; ask twice

Language / i18n

All scripts auto-detect language from $LANG (zh* → Chinese, anything else → English). If the user is conversing with you in Chinese but their shell $LANG is en_US.UTF-8 (common on macOS), the disk report will come out in English — which is wrong.

Fix: before invoking any script, export CLEAN_MY_MAC_LANG to match the conversation language. This always wins over $LANG:

CLEAN_MY_MAC_LANG=zh ~/.claude/skills/cleanmymac/scripts/autoclean.sh
CLEAN_MY_MAC_LANG=en ~/.claude/skills/cleanmymac/scripts/diskmap.sh

The override flows into every downstream script via MAC_LANG (exported by lib.sh). Translation dictionary lives in references/i18n.sh — keyed on English source strings, gettext-style. Adding a string: wrap with $(i18n "English literal") at the call site, add a case branch under _i18n_zh.

References

• whitelist.txt — paths safe_rm is allowed to touch
• whitelist.md — whitelist explained in prose
• safety-rules.md — invariants every script enforces
• cleanup-catalog.md — every module's purpose, size, recovery
• i18n.sh — translation dictionary (add a new language = new _i18n_<code> function + dispatch branch)