mole-mac-cleaner

Q: How do I install mole-mac-cleaner?

Run npx skills add https://github.com/reason-machines/trending-skills --skill mole-mac-cleaner in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/mole-mac-cleaner/ (personal) or .claude/skills/mole-mac-cleaner/ (project).

by reason-machines

Deep clean and optimize your Mac using the Mole CLI tool

Installs: 1.4K
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/reason-machines/trending-skills --skill mole-mac-cleaner

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads mole-mac-cleaner automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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

FAQ

What does the mole-mac-cleaner skill do?

Deep clean and optimize your Mac using the Mole CLI tool

How do I install mole-mac-cleaner?

Run npx skills add https://github.com/reason-machines/trending-skills --skill mole-mac-cleaner in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/mole-mac-cleaner/ (personal) or .claude/skills/mole-mac-cleaner/ (project).

Which AI agents can use mole-mac-cleaner?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is mole-mac-cleaner safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains mole-mac-cleaner?

It is published by reason-machines in reason-machines/trending-skills. It has 1,409 recorded installs.

Popular other skills

View category →

hyperframes-cli

heygen-com/hyperframes

The HyperFrames CLI by job - scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history - plus reading its JSON and recovering from build or render failures.

1.3M installs

triage

mattpocock/skills

Move issues and external PRs through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs.

1M installs

ask-matt

mattpocock/skills

Ask which skill or flow fits your situation. A router over the skills in this repo.

778.4K installs

to-questionnaire

mattpocock/skills

Turn a decision you can't fully answer into a questionnaire for someone else to fill in.

508.9K installs

wait-what

mattpocock/skills

Stop. That last message did not land: re-pitch it.

459.7K installs

loop-me

mattpocock/skills

Grill me about specs for the workflows I want to build, within this workspace.

447.9K installs

mole-mac-cleaner

Install

Install

Describe the task

Review the result

SKILL.md

Mole Mac Cleaner

Installation

Core Commands

Safe Preview Before Deleting

Key Command Details

mo clean — Deep Cleanup

mo uninstall — Smart App Removal

mo optimize — System Refresh

mo analyze — Disk Explorer

mo status — Live Dashboard

mo purge — Project Artifact Cleanup

mo installer — Installer File Cleanup

Configuration Files

Shell Tab Completion

Touch ID for sudo

Scripting & Automation Patterns

Check disk health in a script

Get largest directories as JSON and process with jq

Automated project purge in CI teardown

Raycast / Alfred quick launchers

Safety Boundaries

Troubleshooting

Update & Remove

FAQ

More from reason-machines/trending-skills

Popular other skills

`mo clean` — Deep Cleanup

`mo uninstall` — Smart App Removal

`mo optimize` — System Refresh

`mo analyze` — Disk Explorer

`mo status` — Live Dashboard

`mo purge` — Project Artifact Cleanup

`mo installer` — Installer File Cleanup