mac-cleanup-disk
Skill14 starsChanged 6 months agoMITView on GitHub
macOS disk deep-clean and maintenance workflow, built on tw93/mole (brew install mole, CLI name `mo`). Trigger words "clean mac", "clean system", "disk full", "free up disk", "clear caches", "uninstall app", "disk analysis", "mole", "mo clean", "clean node_modules", "clean build artifacts", "mac maintenance", "deep clean mac", "清理 mac", "清理系统", "磁盘空间不足", "磁盘满", "清理缓存", "卸载应用", "磁盘分析", "清理 node_modules", "清项目构建产物", "mac 维护". Safety policy dry-run first + explicit user text confirmation before any deletion. Sister skill mac-cleanup-process (processes, never touches disk).
- Deletes or force-pushes
- Installs packages
In this repository14 other files it gives its agents.
- app-icon-generatorSkill
- break-itSkill
- debug-modeSkill
- dev-launcherSkill
- diagram-proSkill
- image-uploadSkill
- localizeSkill
- mac-app-uninstallSkill
- mac-cleanup-memorySkill
- mac-cleanup-processSkill
- macos-app-scaffoldSkill
- npm-safetySkill
- root-causeSkill
- skill-scanSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 4 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
Before any workflow, verify mole is installed:
- Very specific: line 18
If it isn't installed, don't proactively brew install — report "mole not installed, requires brew install mole.
- Distinctive: line 22
Don't jump in just because the user said "clean my Mac".
- Distinctive: line 31
If the user already knows which command they want ("I just want to run mo clean"), skip this step and go straight to the safety flow.
- Distinctive: line 76
After each step, report freed space and ask "continue to next step?".
- Very specific: line 82
If the user just wants to know which project directories are eating space, the AI can use find instead:
- Very specific: line 125
After a real deletion, always run df -h / to compare freed space and report "freed X GB, now Y GB available" to the user.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
mac-cleanup-disk
A macOS maintenance workflow based on tw93/mole. Iron rule: preview first, confirm, then execute. Any deletion requires explicit user text confirmation.
0. Pre-flight Check
Before any workflow, verify mole is installed:
which mo && mo --versionIf it isn't installed, don't proactively brew install — report "mole not installed, requires brew install mole. Proceed?" and wait for the user to agree before installing.
1. First Step After a Request: Clarify the Mode
Don't jump in just because the user said "clean my Mac". Lay out the 4 modes first:
| # | Mode | When to use | Main commands |
| 1 | 💨 Daily clean | Periodic maintenance, clear caches and logs | mo clean --dry-run → mo clean |
| 2 | 🔍 Deep clean | Disk space tight, thorough sweep | mo analyze + mo clean + mo installer + mo optimize |
| 3 | 💻 Developer clean | Clean node_modules / target / venv, etc. | mo purge |
| 4 | 🩺 Smart diagnosis | Not sure what to clean — look at data first | mo status + mo analyze + mo clean --dry-run |
If the user already knows which command they want ("I just want to run mo clean"), skip this step and go straight to the safety flow.
2. TUI Restrictions (important!)
The following mole subcommands are full-screen TUI interactive programs. Running them via Claude Code's Bash tool will hang, show no content, and refuse keypresses:
mo(no-args main menu)mo analyzemo uninstallmo purgemo installermo status
Handling principle: let the user run these in their own terminal. The AI must not run them on the user's behalf, and must not timeout-then-kill. The AI's role is:
- Help interpret the TUI output (user screenshots or pastes text back)
- Run non-TUI commands on the user's behalf:
mo clean --dry-run,mo clean,mo optimize --dry-run,mo optimize,df -h
3. Safety Rules (non-negotiable)
- Destructive operations must be preceded by
--dry-run: includesmo clean,mo optimize,mo uninstall,mo purge,mo installer - After the dry-run output, wait for user text reply like "go / continue / confirm / OK" before running the real version — verbal consent counts, silence does not
- Before deep clean, ask: "Have you saved important work? Are dev projects committed?" mole won't touch those, but in case the user picked a destructive mode by mistake
- Stop on error: any non-zero exit from a mo command — report the error immediately, do not retry / do not work around / do not swap commands. Could be a mole bug or permission issue, needs the user's judgment.
- Never proactively run
mo uninstall,mo purge— these may delete files the user is actively using; the user must hand-pick items in the TUI
4. Mode Workflows
4.1 Daily Clean
df -h / # current disk usage snapshot
mo clean --dry-run # list cleanable items + total sizePresent the dry-run output in full to the user (don't omit file categories). After confirmation → mo clean → run df -h / again to compare freed space.
4.2 Deep Clean (multi-step, confirm each step)
In order, confirm each step independently:
- Disk scan: have the user run
mo analyzein their own terminal and paste back the top-10 largest directories - Cache clean: AI runs
mo clean --dry-run --debug→ confirm →mo clean - Installer cleanup: have the user run
mo installerthemselves (TUI, hand-pick) - System optimization: AI runs
mo optimize --dry-run→ confirm →mo optimize
After each step, report freed space and ask "continue to next step?". Don't run the whole sequence non-stop.
4.3 Developer Clean
mo purge is a TUI — let the user run it in their terminal; the AI can't help.
If the user just wants to know which project directories are eating space, the AI can use find instead:
# Scan node_modules in common project directories (sorted by size)
find ~/Documents/Dev ~/Projects ~/GitHub -name node_modules -type d -prune 2>/dev/null \
| xargs -I {} du -sh {} 2>/dev/null \
| sort -hr | head -20Hand the result to the user; they decide whether to run mo purge or rm -rf specific directories manually.
4.4 Smart Diagnosis
df -h / # overall disk usage
du -sh ~/Library/Caches ~/Downloads ~/.Trash 2>/dev/null # frequent heavy consumers
mo clean --dry-run # mole's cleanable itemsRecommend based on the data:
- Disk >85% → recommend deep clean
- Disk 60-85% → recommend daily clean
- Found
node_modules>5GB → also recommend developer clean
Let the user pick a mode, then proceed via the corresponding workflow.
5. mole Command Cheatsheet
| Command | Purpose | Destructive | TUI |
mo status | System monitoring (CPU/mem/disk) | - | ✓ |
mo analyze [path] | Disk-usage visualization | △ | ✓ |
mo clean [--dry-run] | Clear caches/logs/trash | ✓ | - |
mo uninstall | Uninstall app + residuals | ✓ | ✓ |
mo optimize [--dry-run] | Rebuild system caches | △ | - |
mo purge | Clean project build artifacts | ✓ | ✓ |
mo installer | Clean .dmg/.pkg installers | ✓ | ✓ |
mo touchid | Configure sudo Touch ID | △ | - |
Common flags: --dry-run to preview, --debug for verbose logs (including risk level), --whitelist to manage protected paths.
6. After Cleanup
After a real deletion, always run df -h / to compare freed space and report "freed X GB, now Y GB available" to the user. This step is non-negotiable — it's the sanity check.
7. Common Issues
| Symptom | Action |
mo: command not found | brew install mole |
| App slow to launch after cleanup | Normal — caches rebuild once, then back to normal |
| Disk space didn't go down | rm -rf ~/.Trash/* to empty trash; reboot to release swap files |
mo shows garbled output in iTerm2 | Known issue — try Alacritty / kitty / WezTerm / Ghostty / Warp |
Core mindset: you're an assistant, not a janitor. Persuade the user to run the TUI in their own terminal and paste output back for you to interpret — more reliable than running on their behalf, lower cost on error.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

