Mole: The Ultimate Open‑Source macOS Uninstaller and Cleaner

Mole Overview

Mole is a macOS‑only command‑line cleaning and optimization utility that combines several common maintenance functions into a single tool.

System cleaning : clears caches, logs, browser residues, etc.

App uninstall : removes the .app bundle and related preferences, caches, launch items, and other leftovers.

Disk analysis : shows directory usage and helps locate large folders and files.

System optimization : refreshes caches, rebuilds system databases, resets network services, refreshes Finder/Dock, cleans diagnostic logs, removes swap files, and rebuilds launch services and Spotlight index.

Real‑time monitoring : displays CPU, memory, disk, network, process usage and a health score.

Project garbage cleaning : deletes build artifacts such as node_modules, target, build, dist, venv, etc.

Installer file cleaning : finds and removes common installer packages like .dmg, .pkg, .zip.

Touch ID for sudo : configures sudo to accept Touch ID authentication.

Shell completion : sets up tab‑completion for the mo command.

Installation Methods

1) Homebrew

brew install mole

2) Script

curl -fsSL https://raw.githubusercontent.com/tw93/mole/main/install.sh | bash

The script supports installing the latest main‑branch build ( -s latest) or a specific version ( -s 1.17.0).

Basic Usage

After installation, the primary command is mo, which launches an interactive menu. mo --help Use mo --version to view the installed version.

Common Commands

1. Clean System Garbage

mo clean

Targets application caches, browser caches (Chrome/Safari/Firefox), developer tool caches (Xcode, Node.js, npm), system logs, temporary files, app‑specific caches, and the Trash. Use mo clean --dry-run to preview deletions, and add --debug for detailed logs.

2. Uninstall Application

mo uninstall

Deletes the .app bundle and attempts to clean related residues such as Application Support, Caches, Preferences, Logs, WebKit storage, Cookies, plugins, extensions, and launch agents/daemons. Preview with mo uninstall --dry-run.

3. Optimize System

mo optimize

Performs actions like rebuilding system databases, resetting network services, refreshing Finder/Dock, cleaning diagnostic logs, removing swap files, and rebuilding launch services and Spotlight index. Use mo optimize --dry-run or --whitelist to exclude specific steps.

4. Analyze Disk Usage

mo analyze

Launches an interactive disk analyzer that lists directories (e.g., Library, Downloads, Movies, Documents) and large archive files. By default it skips /Volumes to speed up start‑up; specify a path to analyze external disks ( mo analyze /Volumes).

5. Real‑time System Status

mo status

Shows a dashboard with CPU, memory, disk, power/temperature, network, process usage and a health score. Press k to toggle the cat mascot and q to quit.

6. Clean Project Build Artifacts

mo purge

Scans for typical build directories ( node_modules, target, build, dist, venv) and permanently deletes them. Recent projects (within 7 days) are marked and not selected by default. Install fd ( brew install fd) to improve scanning speed. Configure paths via mo purge --paths or edit ~/.config/mole/purge_paths. Preview with mo purge --dry-run.

7. Clean Installer Files

mo installer

Finds and removes installer packages ( .dmg, .pkg, .zip) from locations such as Downloads, Desktop, Homebrew cache, iCloud, and Mail.

8. Configure Touch ID for sudo

mo touchid

Enables Touch ID usage for sudo; the touchid enable sub‑command can be used with --dry-run for preview.

9. Shell Auto‑completion

mo completion

Sets up tab‑completion for the mo command.

10. Update Mole

mo update

If installed via the script, mo update --nightly upgrades to the latest unreleased build.

11. Uninstall Mole

mo remove

Removes Mole from the system.

Important Safety Tips

All destructive commands ( mo clean, mo uninstall, mo purge, mo installer) permanently delete files. Always run with --dry-run first.

For more detail, add --debug to the dry‑run.

Logging

Operations are logged to ~/.config/mole/operations.log. Set the environment variable MO_NO_OPLOG=1 to disable logging.

Interactive Navigation

The interactive UI supports arrow keys and Vim‑style navigation ( h/j/k/l) for quick movement and selection.

Suggested Onboarding Workflow

View help: mo --help Preview system cleaning: mo clean --dry-run Inspect large directories: mo analyze If you are a developer, preview project cleanup: mo purge --dry-run When satisfied, execute the actual commands, e.g., mo clean and mo purge.

Occasionally run mo optimize for system refresh.

Use mo uninstall to remove specific apps.

Who Should Use Mole

macOS users who want a unified terminal‑based cleanup solution.

Developers needing to purge build artifacts.

Anyone who frequently installs/uninstalls software.

Users with limited disk space who need to reclaim storage quickly.

People who prefer managing system state from the command line.

Precautions

Deletion is irreversible; always preview with --dry-run before running mo clean, mo uninstall, mo purge, or mo installer. mo purge removes project dependencies and build outputs, which may disrupt workflows if the project state is unknown. mo optimize refreshes system services and should be used only when the system feels sluggish, not as a routine operation.

Command Quick Reference

mo                     # Interactive menu
mo clean               # Deep system cleanup
mo uninstall           # Uninstall app and clean residues
mo optimize            # System optimization
mo analyze             # Disk usage analysis
mo status              # Real‑time monitoring
mo purge               # Clean project build artifacts
mo installer           # Remove installer files
mo touchid             # Configure sudo Touch ID
mo completion          # Enable shell completion
mo update              # Update Mole
mo remove              # Uninstall Mole
mo --help              # Show help
mo --version           # Show version