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

# Via Homebrew (recommended)
brew install mole

# Via install script (supports version pinning)
curl -fsSL https://raw.githubusercontent.com/tw93/mole/main/install.sh | bash

# Specific version
curl -fsSL https://raw.githubusercontent.com/tw93/mole/main/install.sh | bash -s 1.17.0

# Latest main branch (nightly)
curl -fsSL https://raw.githubusercontent.com/tw93/mole/main/install.sh | bash -s latest

Core Commands

mo                    # Interactive menu (arrow keys or vim h/j/k/l)
mo clean              # Deep system cache + browser + dev tool cleanup
mo uninstall          # Remove apps plus all hidden remnants
mo optimize           # Rebuild caches, reset network, refresh Finder/Dock
mo analyze            # Visual disk space explorer
mo status             # Live real-time system health dashboard
mo purge              # Remove project build artifacts (node_modules, target, dist)
mo installer          # Find and remove installer .dmg/.pkg files

mo touchid            # Configure Touch ID for sudo
mo completion         # Set up shell tab completion
mo update             # Update Mole
mo update --nightly   # Update to latest unreleased build (script install only)
mo remove             # Uninstall Mole itself
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

# Combine with debug for detailed output
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                  # Interactive cleanup
mo clean --dry-run        # Preview what would be removed
mo clean --whitelist      # Manage protected caches (exclude from cleanup)

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              # Interactive multi-select list
mo uninstall --dry-run    # Preview removals

`mo optimize` — System Refresh

mo optimize               # Run all optimizations
mo optimize --dry-run     # Preview
mo optimize --whitelist   # Exclude specific optimizations

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                # Analyze home directory (skips /Volumes by default)
mo analyze ~/Downloads    # Analyze specific path
mo analyze /Volumes       # Include external drives explicitly

# Machine-readable output for scripting
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                 # Real-time CPU, GPU, memory, disk, network, processes
mo status --json          # JSON output for scripting
mo status | jq '.health_score'   # Auto-detects pipe → outputs JSON

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                  # Interactive multi-select
mo purge --dry-run        # Preview
mo purge --paths          # Configure custom scan directories

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              # Find .dmg/.pkg files in Downloads, Desktop, Homebrew cache, iCloud, Mail
mo installer --dry-run    # Preview removals

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             # Interactive setup for bash/zsh/fish

Touch ID for sudo

mo touchid                # Enable Touch ID authentication for sudo commands
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  # swap to `mo clean` when ready
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
# Non-interactive purge of build artifacts after CI
MO_NO_OPLOG=1 mo purge --dry-run   # always preview first in scripts

Raycast / Alfred quick launchers

curl -fsSL https://raw.githubusercontent.com/tw93/mole/main/install.sh | bash
# Then bind `mo clean`, `mo status`, `mo analyze` as script commands in Raycast

Safety Boundaries

mo analyze moves files to Trash via Finder (recoverable) instead of direct deletion — prefer it for ad hoc cleanup
clean, 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                 # Update to latest stable
mo update --nightly       # Update to latest main (script install only)
mo remove                 # Uninstall Mole completely
mo remove --dry-run       # Preview what remove would delete

mole-mac-cleaner