Documentation

Overview

Mole has two interfaces with the same cleanup scope, safety rules, and protection lists. The CLI is free, open source, and GPL-3.0 licensed. The Mac app is a native SwiftUI companion with a $19 one-time license, lifetime updates, and no subscription. It uses native execution for the Mac workflows; the CLI adds a few terminal-only commands.

Mac App

Installation

Download the DMG from the home page, or install via Homebrew: brew install --cask mole-app.

Clean (Earth)

Scans ten categories: app caches, system caches, logs, developer tools (Xcode, npm, pip, Gradle), AI tools (ChatGPT, Claude, Codex, Copilot, Cursor, Antigravity), browsers (Chrome, Edge, Arc, Safari, Firefox), cloud storage clients, design tools (Adobe, Figma, Sketch), communication apps (Slack, Discord, WeChat, Zoom), and miscellaneous temp files. The Trash is listed separately at the end.

The review list is sorted by deletion impact: regenerable caches appear first, user-visible state last, Trash always at the bottom. Hardlink-aware sizing means files shared across tools (uv, pnpm) are not double-counted. Default deletion is permanent so the freed bytes match the headline. One toggle in Settings routes everything through the system Trash instead.

Review-only by default: package caches with real rebuild cost (npm, yarn, pnpm, bun, CocoaPods, Gradle, Maven) and common project output (build, dist, target, .build, node_modules, venv). These folders can be large, but stay unchecked until you confirm. Auto-clean items arrive pre-checked; Settings can route cleanup through Trash.

Software (Mars)

Software combines app updates, startup management, and uninstall cleanup. The Updates view checks Sparkle, Homebrew Cask and Formula, and Mac App Store apps, then installs supported updates in place or opens the App Store when macOS requires that handoff.

The Startup view lists Login Items, Launch Agents, Launch Daemons, and background items. You can disable supported entries, reveal their files, or jump to System Settings for Apple-managed items.

For uninstall, pick apps to remove. Mole finds leftover files in fifteen-plus Library subdirectories, including Application Support, Caches, Preferences, Logs, Launch Agents, Launch Daemons, Login Items, Containers, Group Containers, Saved Application State, and Input Methods. Dock entries are cleaned automatically, and ambiguous or weakly matched leftovers stay visible but unselected for review.

Updates ship in-app where possible: Sparkle and Homebrew Cask installs run inside Mole; Mac App Store updates go through CommerceKit and fall back to the App Store app on auth or timeout issues; other apps open so their own updater can take over. Cmd-click adds rows to a multi-uninstall batch, and any per-app failure stays in the list for retry.

Root-owned /Applications/*.app bundles need one administrator confirmation on first removal in a session; later removals reuse the same authorization until you quit Mole. The Startup view toggles login items and validated LaunchAgents / LaunchDaemons directly when it can match them to a stable launchd service; entries managed by macOS background task management without a clear handle are routed to the matching System Settings pane instead.

Optimize (Mercury)

Default maintenance tasks run with one tap. Non-admin tasks run silently; admin tasks are batched behind one prompt when needed.

Optimize starts with a visible fix pass for self-healing services such as Dock, input-method switching, iCloud Drive sync, AirDrop, Spotlight, and Notification Center. Deeper tasks include: rebuild Quick Look, font cache and Launch Services garbage collection; vacuum SQLite stores; clean saved application state, quarantine events and notification history; repair broken preferences, Launch Agents, shared file lists, and orphaned Spotlight rules; audit login items; and run periodic maintenance.

Safety gates skip tasks when conditions are unsafe: font cache rebuild is skipped when browsers are open, and DNS or network-stack resets are not part of the default maintenance set.

Optimize also skips device-touching tasks when an active VPN, Bluetooth HID or audio, or an external display or audio device is detected; skipped tasks list a reason in the result panel so you can see what ran.

Analyze (Jupiter)

A treemap visualization of your entire disk. Drill down into any directory to see size at every level, with dense or similar items folded into summary blocks so the map stays readable.

Entries that could not be sized (permission-restricted folders, TCC-gated containers) are surfaced with a retry option instead of being silently dropped. Protected navigational roots (/, /Users, /Applications) cannot be trashed. Disk scan results are cached for 24 hours for fast re-entry.

Single-click a directory in the treemap to drill in; the breadcrumb row above the map jumps back to any ancestor. The left list and real treemap blocks both keep item actions: open or reveal in Finder, and right-click for Move to Trash with confirmation. Summary blocks are overview-only. Block area in the treemap is proportional to byte size, so the biggest space hogs always sit visually largest.

Status (Sun)

A bento dashboard shows Health, CPU, GPU, Memory, Battery or Thermal, Disk, Network, and a hardware-dependent Fans or Thermal tile. Each metric carries a 60-second sparkline, and supported Macs expose fan controls for Auto, Cool, and Max modes.

The process list below the grid updates every second. Click any column header (Name, CPU, Memory) to sort. Click a row to pin it; pinned processes stay at the top across refreshes so you can watch a specific app without losing it in the scroll.

All five columns (Name, PID, CPU, Power, Memory) sort on click; click again to flip direction. Right-click a row for Pin/Unpin (kept across refreshes and app restarts), Terminate (a graceful TERM with a forced KILL fallback), and Copy Executable Path. The Battery tile's top-drain row links directly to that process in the explanation sheet.

Menu bar HUD

An optional always-on monitor in the macOS menu bar. Choose live metrics, a compact icon, or a small runner animation whose motion follows system load. Pick from Mole, Ahu, RunCat, Shelly, Ember, Kong, Russet, Flex, Pixel, or a static silhouette. The popover shows a Health hero (score, chip, memory, macOS, uptime), hardware tiles, fan controls where supported, top five CPU processes, and a Clean Watch lifetime summary.

Quick tools live at the bottom of the popover: privacy signal indicators light up when the camera or microphone is in use, Keep Screen On has a duration menu (1h / 4h / Until I stop), Clean Screen turns the screen into a plain color so you can wipe the display and keyboard with an optional Accessibility-gated input lock, and an Eject button appears there when an external drive or disk image can be unmounted. A customizable global keyboard shortcut summons Mole from anywhere, and hiding the Dock icon turns it into a menu-bar-only app. Configure everything under Settings → Menu Bar.

Per-app privacy alerts. When an alert names an app, hover over the macOS notification and choose Stop notifying for this app. Restore it later under Settings → Menu Bar → Notifications → Apps without privacy alerts. A camera-only alert stays generic because macOS does not expose its owning app, so Mole does not offer a per-app action on that alert.

Display Mode picks between the runner animation and a Metrics view of two configurable rows. Each row can independently show CPU, Memory, Temperature, Disk, or Network. The runner choice is purely visual and never changes which metrics are sampled.

Doctor

From the menu bar: Help → Run Doctor…. Mole gathers a short read-only diagnostic report covering your Mac model, macOS version, permissions, recent operations, display, external volumes, network, security state, and environment. Click Copy Report for a lightweight chat summary, or Copy Terminal Command to generate the full support bundle for private email support.

Doctor detects five conditions: missing Full Disk Access, elevated memory pressure, disk usage above 90%, unwritable operations log, and recent operation failures. Each condition links to a help article with resolution steps. See the Help page for details on each.

Settings

Settings has three tabs. General: interface Language (applies after a relaunch), Launch at Login, Hide Dock Icon, License activation and device management, and a Full Disk Access shortcut. Maintenance: Cache Removal mode (Permanent deletion, the default for caches, or Trash routing) and Protected Items whitelist. Battery Care keeps the built-in battery between 75% and 80% while Mole runs to slow wear, on supported Macs with one admin approval. Menu Bar: enable the Menu Bar Monitor, pick a runner or switch to live metrics, choose visible metrics for both runner lines, configure fan behavior where supported, record custom keyboard shortcuts for Menu Bar Toggle / Keep Screen On / Clean Screen, toggle Clean Screen Input Lock (Accessibility), and turn Privacy Signal and Keep Screen On notifications on or off. License activation is also reachable any time with Cmd + Shift + L.

CLI

Installation

Via Homebrew: brew install mole. Via script: curl -fsSL https://raw.githubusercontent.com/tw93/mole/main/install.sh | bash. Run mo for the interactive menu, or any subcommand directly.

Shared commands (also in the Mac app)

mo clean

Deep cleanup across the same ten categories as the Mac app. Supports --dry-run to preview without deleting, --debug for detailed logs, and --whitelist to manage protected caches. Skips caches of running apps automatically.

mo uninstall

Interactive app selection with remnant detection. Shows app size, bundle ID, and last-used date. Finds the same fifteen-plus leftover categories as the Mac app. Supports --dry-run.

mo optimize

Runs CLI maintenance tasks with admin prompts when needed. Its exact task set can differ from the Mac app's default Optimize list. Use --whitelist to exclude specific tasks from future runs.

mo analyze

Interactive treemap in the terminal. Navigate with arrow keys or Vim bindings (h/j/k/l). Trash files directly from the map. Supports --json output and custom paths like mo analyze /Volumes for external drives.

mo status

Live system dashboard: CPU, GPU, memory, disk I/O, network, battery, thermals, uptime, health score, and top processes with sixty-second sparklines. Supports --json for piping to other tools.

CLI-only commands

mo purge

Finds old build artifacts across project directories: node_modules, target, .build, build, dist, venv. Scans configurable paths (default: ~/Projects, ~/GitHub, ~/dev). Projects younger than 7 days are marked "Recent" and unselected by default. Supports --dry-run and --paths to configure scan directories.

mo installer

Discovers .dmg, .pkg, and .zip installer files in Downloads, Desktop, Homebrew cache, iCloud, and Mail attachments. Labels each file by source location. Supports --dry-run.

mo touchid

Enables Touch ID for sudo commands. Run mo touchid enable to configure, mo touchid disable to revert. Supports --dry-run.

Utility commands

mo completion

Sets up shell tab completion for Bash and Zsh. Auto-detects your shell and updates the appropriate config file.

mo update

Self-update to the latest stable release. Use --nightly for the latest unreleased build from main (script installs only). Use --force to reinstall the current version.

mo remove

Uninstalls Mole CLI from your system, including config files and shell integration. Supports --dry-run.

Safety

Both the CLI and Mac app share the same safety principles:

Path protection. A built-in deny list covers system-critical directories, your home folder's essential structure, and anything outside known cache locations. Symlinks are resolved and validated before any operation.

Process awareness. Caches belonging to running apps are skipped during cleanup. Browser caches are not touched while the browser is open.

License gate. In the Mac app, each destructive tool (Clean, Uninstall, Optimize, Analyze trash) works twice for free. After that, an active license is required. Scanning is always free.

Whitelist. Both the CLI (~/.config/mole/whitelist) and Mac app let you protect specific caches or optimization tasks from future runs.

Operations log. Every deletion is recorded at ~/Library/Logs/mole/operations.log. The Mac app's Doctor overlay checks the health of this log and surfaces any recent failures.

Preview first. The CLI supports --dry-run on every destructive command. The Mac app shows the full file list and byte count before any action.

Troubleshooting

The Mac app includes a built-in Doctor that detects common issues. Open it from Help → Run Doctor… in the menu bar. For specific conditions, see the Help page.

For the CLI, add --debug to any command for detailed logs. Review the operations log at ~/Library/Logs/mole/operations.log for recent activity. If a command fails silently, check whether Full Disk Access is granted in System Settings.

To report issues, see the Report a problem section on the Help page.