Documentation

Overview

Mole has two interfaces with similar cleanup categories and the same conservative safety rules and protection lists, but their capabilities are not identical. 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, free updates, and no subscription. It provides a graphical interface for cleanup and Mac maintenance; 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.

After an update, See What’s New appears in the title bar until you open or dismiss it. It shows the notes for the running version and the four before it, with a link to all releases at the end, and What’s New in the Mole menu reopens them at any time.

Clean · Earth

Clean starts with app caches, which include browser and cloud-client caches and app logs; developer, AI, communication and design tools have their own groups. Uninstalled-app leftovers follow, then installers left in Downloads or Desktop for over two weeks, then System Data: local Time Machine snapshots, system caches and logs, old macOS installers and stale wallpaper downloads. Trash comes last. The Manage Separately group lists backups, local iCloud files, virtual machines and models, outside the cleanup total.

Review the rows before cleaning. System Data is a macOS storage classification, not a folder or a target size: Mole’s measured files will not match the figure in Storage settings. Hardlink-aware sizing avoids counting shared files twice. Caches are permanently deleted by default, with a Trash option in Settings; releasing local snapshots removes those local restore points, not backups on an external disk. Optional system unified-log cleanup is irreversible and requires its own review.

Review-only by default: package caches with real rebuild cost (npm, yarn, pnpm, bun, CocoaPods, Gradle) and generated project output that can be rebuilt without downloading dependencies (build, dist, target, .build, .next, DerivedData, __pycache__, coverage). Downloaded dependency directories such as Pods and venv are not offered by the Mac app: rebuilding them needs network access and may not reproduce the lockfile state. A project's node_modules is the exception: it is listed once the project has gone 90 days without changes and its lockfile can reinstall it, and it always goes to the Trash. Review-only items stay unselected until you confirm; Settings can route cleanup through Trash.

A separate action under Manage Separately can reclaim unused space inside a supported Parallels virtual disk through Parallels’ own tool. Shut down the VM normally first; suspended or running VMs are not eligible. Review the estimate and confirm separately. The action keeps the VM and its files, does not join bulk cleanup, and must finish without interruption.

AI Cleanup & Care · Moon

When this Mac holds AI tool data, a far Moon appears at the top right of the Clean page and leads to AI Cleanup & Care. The entry shows only when that data is found, the check only looks for a few fixed folders and never walks the disk, and Settings › General › Cleaning can hide it. The page does not scan on arrival; Scan AI data starts it, and a scan that finds something opens the results directly.

Results come in three bands by how much a removal could hurt. Caches and old versions start selected: superseded builds of the Claude Code, Codex, Cursor Agent, Grok and GitHub Copilot command-line tools, including the cursor-agent releases Cursor's desktop app keeps for itself, and caches of Claude, Codex, Cursor and Grok. Sessions and worktrees start unselected: Codex, Claude Code, OpenCode and Devin sessions past a retention window set per tool (15, 30, 90 or 120 days, or Don't list, the default, under which no session is listed and the row shows how many sessions the tool keeps and their size, while each choice shows what it would list), Claude Code sessions past that window whose project folder is gone, images Codex rendered for sessions it already deleted, and worktrees git can prove have no unique changes or commits not retained by a branch, including those whose changes already landed on the main branch. Idle tools and maintenance start unselected: AI command-line tools unused for 30 days and not running, uninstalled with their sessions and settings, compaction of SQLite stores over 200 MB, and config folders left by tools already removed. Old versions, caches, sessions and worktrees can be deselected one entry at a time.

Sessions used in the last 24 hours are never listed, so the page works while Codex and Claude Code are open. Data a running tool holds open stays listed as in use and cannot be selected, and every row is checked again right before it moves. Files go to the Trash; a Codex session is copied to the Trash and then removed with Codex's own command, and the images Codex rendered for it go to the Trash with it; Homebrew-installed tools uninstall through brew; compaction happens in place. Memories, plans and skills are on no row, and of local models only Ollama's appear, unused for a month and removed with its own ollama rm.

Software · Mars

Software combines app updates, startup management, and uninstall cleanup. The Updates view checks Sparkle, Electron, Homebrew Cask and Formula, GitHub Releases, 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. The data an app keeps for itself, such as settings and chats, is selected with the app; browser profiles, data shared with other apps and ambiguous or weakly matched leftovers stay visible but unselected for review, and unticking a section keeps it for a reinstall. Audio plugins and drivers signed by the same developer are listed for review, an app’s folder in /Users/Shared is listed too, and thousands of leftovers with generated names go to the Trash as one folder. Cmd-click adds rows to a multi-uninstall batch, and any per-app failure stays in the list for retry. An app row’s right-click Clear Data Only removes its data while keeping the app.

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.

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 that Mole cannot control directly are routed to the matching System Settings pane instead.

Adobe Genuine Service has an official-uninstaller action. Mole opens Adobe’s installed uninstaller when it can verify it, or offers Adobe’s instructions when it cannot. It rechecks the service afterward; opening the uninstaller alone does not establish removal. TeamViewer and antivirus apps such as Bitdefender, Intego, Kaspersky, Norton and Trend Micro open their developer’s own uninstaller in the same way.

Optimize · Mercury

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

Optimize starts with a visible fix pass for input-method switching, Spotlight, Notification Center, and Universal Clipboard. Deeper tasks include: rebuild Quick Look; vacuum SQLite stores; clean saved application state, quarantine events and notification history; repair broken preferences, shared file lists, and orphaned Spotlight rules; audit login items; move Launch Agents whose program is missing to the Trash; and run periodic maintenance.

Safety gates skip tasks when conditions are unsafe. DNS and network-stack resets are not part of the default maintenance set.

Optimize skips a task when its own check says it is unnecessary, such as the memory purge while memory pressure is healthy or the Mail and Messages database compaction while those apps are running; skipped tasks list a reason in the result panel so you can see what ran. Click the summary line under Maintenance complete to open Optimize details, which lists what ran, what was skipped and why.

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, so reopening shows the last result, and after 6 hours Mole re-measures in the background.

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, which moves the item right away, like Finder, so it can be put back; only items already in the Trash ask first, because deleting them is permanent. Summary blocks are overview-only. Block area in the treemap is proportional to byte size, so the largest items always draw the largest blocks.

The context menu also copies a file or folder path, so it can be pasted into Finder or a support message without removing the item.

Select above the map picks files and folders from different folders; the picks stay while you drill in and go back, and move to the Trash together. Hovering a folder names it and, for more than 5,000 known folders, says in one sentence what it holds and what removing it costs; the largest rows in the side list name the app they belong to. Largest Files marks a file Unused when nothing has opened, written or moved it for a year. When the volume has grown by 1 GB or more since an earlier scan between one and thirty days old, a line shows how much and splits the growth by owner: the Trash, iPhone and iPad backups, Xcode, AI tools and installed apps, each row opening exactly that place.

Status · Sun

The dashboard shows Health, CPU, GPU, Memory, Battery, Disk, Network, and Fans. A Mac without a battery shows Thermal in place of Battery, and a Mac without fans shows Thermal in place of Fans. Trend charts show recent activity, and supported Macs expose fan controls for Auto, Cool, and Max modes; Cool or Max comes back after a shutdown, restart or update, but not after you quit Mole yourself. Every tag on the dashboard opens a card of related readings: the CPU and GPU temperature badges list each named sensor, with the battery, power supply and storage sensors on their own cards, and Memory, Disk, Battery and the chip name each open theirs. The same tags in the menu bar panel open the same cards. Clicking the Network tile's connection tag shows the Mac's local IPv4 address, the public IP with its location and ISP, and the system proxy, while a proxy or VPN is on, the address and country ChatGPT sees, and on Wi-Fi the signal strength and the link's standard, band and rate.

The process list below the grid updates every second. All five columns (Name, PID, CPU, Power, Memory) sort on click; click again to flip direction. Click a row to open its explanation sheet. Right-click a row for Pin Row (pinned processes stay at the top across refreshes and app restarts, so you can watch one app without losing it in the scroll), Why is this running?, Reveal in Finder, Copy Process Name, Copy PID, Terminate (a normal exit request) and Force Quit; protected system processes offer no Terminate or Force Quit. The Battery tile's top-drain row links directly to that process in the explanation sheet.

Menu bar panel

An optional always-on monitor in the macOS menu bar. Show the icon, a small runner whose motion follows system load, live data, or both. Pick from Mole, RunCat, Beagle, Poodle, Dinosaur, Dragon, Horse, Rabbit, Frog, Chicken, Rubber Duck, Otter, Dolphin, Turtle, Fishman, Pixel, Flex, or Lift Bro. The popover shows a Health hero (score, chip, memory, macOS, uptime), hardware tiles, fan controls where supported, top five CPU processes, and a Lifetime summary of what Mole has cleaned, uninstalled and optimized.

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 (1, 2, 4, 8 or 12 hours, or Until Stopped), Clean Screen turns the screen into a plain color so you can wipe the display and keyboard with an optional input lock gated by the macOS Accessibility permission, 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 Hide Dock icon keeps it in the menu bar only while it runs in the background. 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 with alerts turned off. 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.

Menu bar content picks Icon (the runner), Live data with up to three configurable metrics, or Icon and data. Two metrics show by default, and Third status metric adds one more. Each metric shows one of CPU usage, Memory usage, Memory pressure, Swap usage, GPU usage, Disk space used, Chip temperature, Battery level, Power draw, Fan speed, or Accessory battery, and no two can carry the same metric. Show live network speed is a separate switch that adds upload and download beside those metrics. Clicking that pair opens a per-app network list: live speeds, or what each app moved over the last minute, 5, 10 or 30 minutes, day, 7 days or 30 days, with the whole Mac's trend and up to twelve apps. While Mole is in the menu bar, the download and upload readings on the Network card in Status and in the menu bar panel open the same list. Network & Speed Test in the Mole menu and in the menu bar’s right-click menu opens it too. The record runs only while the pair is shown, reads once a minute, and stays on this Mac for 30 days across restarts; time Mole was not running is not in it. Its Speed Test tab starts a test when chosen, using macOS's own networkQuality against Apple's servers, and shows download, upload, latency and latency under load; Mole runs no server of its own. The runner choice is purely visual and never changes which metrics are sampled. Data layout sets the metrics in Columns (the default) or Stacked in a compact two-line band, and Flip direction turns the runner from left to right.

A runner’s animation can be paused without choosing a different character. The native Tools menu exposes Keep Screen On, Clean Screen, fan control on supported Macs, WiFi Low Latency and Hide Desktop Icons. Optional shortcuts open the main window, toggle fan cooling or hide desktop icons. WiFi Low Latency also appears on the Network cards; it temporarily pauses AWDL and AirDrop, and restores the prior state on off, sleep or quit. It does not promise faster downloads. Hide Desktop Icons, also in the Mole menu and the menu bar’s right-click menu, is the same setting as Show items in System Settings › Desktop & Dock, so files and disks stay where they are. Its shortcut is ⌃⌥⌘D by default.

Doctor

In the app, click the Mole logo in the top-left of the window and pick 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 and paste it into your message to support.

Doctor checks six conditions: missing Full Disk Access, high memory pressure, a nearly full disk, low battery health, a recommended restart, and an operations log that cannot be written. Each condition links to a help article with resolution steps. See the Help page for details on each.

Settings

Settings has three tabs. General contains interface Language (applies after a relaunch), Cleaning preferences, Items excluded from cleaning, License activation and device management, Beta updates, and a Full Disk Access shortcut. Cleaning includes Cache removal (Delete permanently, the default, or Move to Trash), Show AI Tool Cleanup & Care, and Quick uninstall. Tools contains Keep Screen On, Clean Screen, their shortcuts and Clean Screen Input Protection (which needs the macOS Accessibility permission), plus Battery Care and fan controls on supported Macs. Battery Care keeps the built-in battery between 75% and 80% while Mole runs, with one admin approval; End fan boost after cooling decides whether Cool and Max hand back to macOS once the Mac has cooled. Menu Bar contains Launch at Login, Hide Dock icon, icon and runner appearance, visible metrics and Network Speed, the Open Mole shortcut, and notifications including Camera and microphone alerts. License activation is also reachable with Cmd + Shift + L.

Terminal options

A few options only some people need are left out of Settings. Run the command in Terminal, then quit and reopen Mole. To show temperatures in Fahrenheit, run defaults write com.tw93.MoleApp temperatureUnitPreference -string fahrenheit; to go back to Celsius, run defaults delete com.tw93.MoleApp temperatureUnitPreference. Only the displayed numbers change; fan curves and warnings still work from the same readings. To set the verses beside the planets in the system font instead of a serif, run defaults write com.tw93.MoleApp poemFontPreference -string system; to bring the serif back, run defaults delete com.tw93.MoleApp poemFontPreference.

CLI

Installation

Install with Homebrew: brew install mole. Run mo for the interactive menu, or any subcommand directly.

Shared commands · also in the Mac app

mo clean

Deep cleanup of caches and temporary files. 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 60-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.

Free trial and activation. In the Mac app, each paid tool (Clean, Software, Optimize, and moving items to Trash in Analyze) 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. In the Mac app, Clean and Uninstall show the full file list and byte count before anything is removed, and Analyze moves single items to the Trash, where they can be put back.

Troubleshooting

The Mac app includes a built-in Doctor that detects common issues. Open it by clicking the Mole logo in the top-left of the window and picking Run Doctor. 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.