Mole Mac Cleaner

Skill by ara.so — Daily 2026 Skills collection.

Mole (

mo

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/

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

↑↓

j/k

←→

h/l

O

F

⌫

L

Q

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

q

mo purge

— Project Artifact Cleanup

Scans for

node_modules

target

build

dist

venv

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/

purge_paths

mo purge

operations.log

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

mo: command not found

brew install mole

$PATH

fd

brew install fd

mo analyze /Volumes

mo clean --whitelist

mo optimize --whitelist

--dry-run

MO_NO_OPLOG=1

--nightly

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