mole

name	mole
description	Drive Mole (`mo`), tw93's GPL-3.0 macOS maintenance CLI that cleans caches and app leftovers, uninstalls apps with their remnants, purges rebuildable project artifacts, removes downloaded installers, explores disk usage, runs bounded system optimization, and reports live health. Routes one request to one mode: run a command safely (`--dry-run` first, the user runs the destructive step), consume the JSON/NDJSON agent surfaces (`mo analyze --json`, `mo status --json` / `--watch`, `mo history --json`, `~/.config/mole/clean-list.txt`), install/update/remove on the right channel, configure whitelists and scan paths, troubleshoot, or contribute to the repo. Use when a user wants to free Mac disk space or fully uninstall a Mac app. Triggers on: mole, `mo clean`, `mo uninstall`, `mo analyze`, `mo purge`, `mo status`, tw93/Mole, mole.fit, clean my Mac, what is eating my disk, CleanMyMac / AppCleaner / DaisyDisk alternative, brew install mole.
allowed-tools	Bash Read Write Edit Glob Grep
compatibility	macOS only (10.14+, Intel and Apple Silicon); `install.sh` hard-fails on non-Darwin. Windows support is an experimental `windows` branch. Needs the stock Bash 3.2+ and admin rights for some cleanup. Full Disk Access is recommended, not required. Optional `fd` speeds up `purge`/`installer`. Go 1.24+ only to build the `analyze`/`status` TUI binaries. The CLI is GPL-3.0; the "Mole for Mac" GUI at mole.fit is a separate paid product.
metadata	{"tags":"mole, macos, cleanup, uninstaller, disk-analyzer, system-monitor, cli, tui, maintenance, homebrew, go, bash","platforms":"Claude, ChatGPT, Gemini, Codex","version":"1.0","source":"https://github.com/tw93/Mole"}

Mole — macOS cleanup, uninstall, analyze, optimize, monitor

Mole is a terminal-first macOS maintenance toolkit: a Bash CLI (mole, aliased mo) plus two Go/Bubble Tea TUI binaries (analyze-go, status-go). It reclaims disk space, removes apps together with their remnants, purges rebuildable project artifacts, and reports system health — with dry-run previews, path protection, and an operations log on every destructive path.

It deletes files on someone's live machine. That single fact drives every rule below.

When to use this skill

• A user wants to free disk space, find what is eating their disk, or fully uninstall a Mac app including leftovers
• Reading Mole's machine-readable output (--json / --watch / the dry-run list file) instead of scraping a TUI
• Installing, updating, or removing Mole, or untangling a Homebrew-vs-script install-channel conflict
• Configuring whitelists, purge scan paths, shell completion, or Touch ID
• Diagnosing a Mole run that skipped everything, hung, or asked for permissions
• Contributing to the tw93/Mole repo (Bash 3.2 + Go, bats tests, the # SAFE: deletion contract)

When not to use this skill

• Non-macOS cleanup, or Linux/Windows disk tooling → Mole is Darwin-only
• Questions about the paid Mole for Mac GUI (mole.fit) → separate closed-source product, not this repo; the CLI is not a feature mirror of it
• Generic "delete these files for me" work with no Mole involved → use plain shell; do not route arbitrary deletions through Mole
• Package management, app installation, or background monitoring → explicitly out of scope per the project's own product filter

Instructions

Step 0: The five rules (non-negotiable)

These come from the project's own agent guide (.claude/skills/mole/SKILL.md upstream) and override convenience:

1. Preview before you delete. Always. Every destructive command takes --dry-run. Run it, show the user what would go, then offer the real run. The dry-run is the undo.
2. The user runs the destructive command, not you — unless they asked for it in this turn. "Clean my Mac" is such an ask; "why is my disk full" is not.
3. Never parse a TUI frame. mo analyze and TTY-attached mo status are full-screen Bubble Tea programs whose output is drawn, not printed. Use the JSON surfaces.