Mole Mac Cleaner
Skill by ara.so — Daily 2026 Skills collection.
Mole (mo) is an all-in-one macOS maintenance CLI that combines deep cleaning, smart app uninstallation, disk analysis, system optimization, live monitoring, and project artifact purging into a single binary.
Installation
brew install mole
curl -fsSL https://raw.githubusercontent.com/tw93/mole/main/install.sh | bash
curl -fsSL https://raw.githubusercontent.com/tw93/mole/main/install.sh | bash -s 1.17.0
curl -fsSL https://raw.githubusercontent.com/tw93/mole/main/install.sh | bash -s latest
Core Commands
mo
mo clean
mo uninstall
mo optimize
mo analyze
mo status
mo purge
mo installer
mo touchid
mo completion
mo update
mo update --nightly
mo remove
mo --help
mo --version
Safe Preview Before Deleting
Always dry-run destructive commands first:
mo clean --dry-run
mo uninstall --dry-run
mo purge --dry-run
mo clean --dry-run --debug
mo optimize --dry-run --debug
Key Command Details
mo clean — Deep Cleanup
Cleans user app caches, browser caches (Chrome, Safari, Firefox), developer tool caches (Xcode, Node.js, npm), system logs, temp files, app-specific caches (Spotify, Dropbox, Slack), and Trash.
mo clean
mo clean --dry-run
mo clean --whitelist
Whitelist config lives at ~/.config/mole/. Edit it to protect paths you want to keep.
mo uninstall — Smart App Removal
Finds apps, shows size and last-used date, then removes the app bundle plus all related files:
- Application Support, Caches, Preferences
- Logs, WebKit storage, Cookies
- Extensions, Plugins, Launch Daemons
mo uninstall
mo uninstall --dry-run
mo optimize — System Refresh
mo optimize
mo optimize --dry-run
mo optimize --whitelist
Optimizations include:
- Rebuild system databases and clear caches
- Reset network services
- Refresh Finder and Dock
- Clean diagnostic and crash logs
- Remove swap files and restart dynamic pager
- Rebuild launch services and Spotlight index
mo analyze — Disk Explorer
mo analyze
mo analyze ~/Downloads
mo analyze /Volumes
mo analyze --json ~/Documents
JSON output example:
{
"path": "/Users/you/Documents",
"entries": [
{ "name": "Library", "path": "...", "size": 80939438080, "is_dir": true }
],
"total_size": 168393441280,
"total_files": 42187
}
Navigator shortcuts inside mo analyze:
| Key |
Action |
↑↓ or j/k |
Navigate list |
←→ or h/l |
Go back / Enter directory |
O |
Open in Finder |
F |
Reveal in Finder |
⌫ |
Move to Trash (via Finder, safer than direct delete) |
L |
Show large files |
Q |
Quit |
mo status — Live Dashboard
mo status
mo status --json
mo status | jq '.health_score'
JSON output example:
{
"host": "MacBook-Pro",
"health_score": 92,
"cpu": { "usage": 45.2, "logical_cpu": 8 },
"memory": { "total": 25769803776, "used": 15049334784, "used_percent": 58.4 },
"disks": [],
"uptime": "3d 12h 45m"
}
Shortcuts inside mo status: k toggles the cat mascot, q quits.
mo purge — Project Artifact Cleanup
Scans for node_modules, target, build, dist, venv, and similar directories. Projects newer than 7 days are unselected by default.
mo purge
mo purge --dry-run
mo purge --paths
Configure custom scan paths (~/.config/mole/purge_paths):
~/Documents/MyProjects
~/Work/ClientA
~/Work/ClientB
When this file exists, Mole uses only those paths. Otherwise it defaults to ~/Projects, ~/GitHub, ~/dev.
Install fd for faster scanning: brew install fd
mo installer — Installer File Cleanup
mo installer
mo installer --dry-run
Configuration Files
All config lives in ~/.config/mole/:
| File |
Purpose |
purge_paths |
Custom directories for mo purge to scan |
operations.log |
Log of all file operations |
Disable operation logging:
export MO_NO_OPLOG=1
mo clean
Shell Tab Completion
mo completion
Touch ID for sudo
mo touchid
mo touchid enable --dry-run
Scripting & Automation Patterns
Check disk health in a script
#!/bin/bash
health=$(mo status --json | jq -r '.health_score')
if [ "$health" -lt 70 ]; then
echo "Health score low: $health — running cleanup"
mo clean --dry-run
fi
Get largest directories as JSON and process with jq
mo analyze --json ~/Downloads | jq '.entries | sort_by(-.size) | .[0:5] | .[] | {name, size_gb: (.size / 1073741824 | . * 100 | round / 100)}'
Automated project purge in CI teardown
#!/bin/bash
MO_NO_OPLOG=1 mo purge --dry-run
Raycast / Alfred quick launchers
curl -fsSL https://raw.githubusercontent.com/tw93/mole/main/install.sh | bash
Safety Boundaries
mo analyze moves files to Trash via Finder (recoverable) instead of direct deletion — prefer it for ad hoc cleanupclean, uninstall, purge, installer, and remove are permanently destructive — always --dry-run first- Mole validates paths and enforces protected-directory rules; it skips or refuses high-risk operations
- Operation log:
~/.config/mole/operations.log — disable with MO_NO_OPLOG=1
- Review SECURITY.md and SECURITY_AUDIT.md before using in automated pipelines
Troubleshooting
| Problem |
Solution |
mo: command not found |
Run brew install mole or re-run install script; check $PATH |
| Purge scan is slow |
Install fd: brew install fd |
| External drives not appearing in analyze |
Run mo analyze /Volumes explicitly |
| Want to protect a cache from being cleaned |
Run mo clean --whitelist to add it |
| Need to exclude an optimization step |
Run mo optimize --whitelist |
| Script getting interactive prompts |
Use --dry-run flag; check for MO_NO_OPLOG=1 env var |
| Nightly update not working |
Nightly updates (--nightly) only work with script install, not Homebrew |
Update & Remove
mo update
mo update --nightly
mo remove
mo remove --dry-run
