mole-mac-cleanup
Safely operate the installed Mole CLI (`mo`) on macOS using machine-readable status, analysis, history, and dry-run surfaces. Use when Claude Code is asked to inspect Mac disk, CPU, memory, or network
SKILL.mdplatforms/claude/skills/mole-mac-cleanup/SKILL.md
GitHubMole Mac Cleanup
Use the official Mole agent skill at tw93/Mole/.claude/skills/mole/SKILL.md as the command-semantics baseline. The repo-only runtime.yaml pins the audited upstream version. For version-sensitive behavior, confirm the installed version and read mo <command> --help; trust the actual dry-run over stale assumptions.
Safety Contract
- Always preview before deletion. Run the matching
--dry-run, inspect its candidates, summarize the impact, and obtain explicit user confirmation in the current turn before running the destructive command. - Treat
clean,uninstall,purge,installer, andoptimizeas destructive. Treatupdate,remove, and whitelist changes as state-changing and require an explicit request. - Never parse or act from a TUI frame. Use JSON surfaces where available. If a selector opens, do not infer a selection or press bulk-select keys on the user's behalf.
- Never invent flags. Run
mo <command> --helpwhen the documented surface is insufficient. - Preserve Mole's safety layer. Use
mo clean --whitelistfor protected paths; never replace Mole with rawrm, hand-written recursive deletion, or broad globs. - Do not request
sudo, close applications, remove login items or dotfiles, prune Docker/OrbStack, or delete virtualenvs and project artifacts unless the user separately confirms that exact scope. - Bound long scans and watches. Send progress updates, stop low-value scans that remain silent, and never leave
mo status --watchrunning in the background.
Establish the Runtime
Confirm the binary, version, and real package manager:
command -v mo
mo --version
brew list --versions mole
brew info mole --json=v2
Do not trust the Install: line from mo --version alone; a Homebrew-managed build can report Manual. If brew list --versions mole succeeds, manage it with Homebrew.
Choose the Surface
| User intent | Agent-facing command |
|---|---|
| Explain disk usage | mo analyze --json or mo analyze --json <path> |
| Preview safe cleanup | mo clean --dry-run |
| List installed apps with exact uninstall names | mo uninstall --list |
| Remove one app completely | mo uninstall --list to read the exact name, then mo uninstall --dry-run <app> |
| Preview bounded maintenance | mo optimize --dry-run |
| Preview old project artifacts | mo purge --dry-run |
| Preview downloaded installers | mo installer --dry-run |
| Audit prior cleanup | mo history --json --limit 20 |
| Capture one health snapshot | mo status --json |
| Capture a short time series | mo status --watch --interval 1s |
Interactive analyze, terminal-attached status, app selectors, and installer selectors are human surfaces. Prefer the commands above. If a dry-run still opens a selector, stop after reporting the visible candidates and ask the user to make the selection.
Machine-Readable Evidence
Disk analysis
mo analyze --json returns one JSON object containing path, overview, and entries[]. Each entry includes name, path, size, is_dir, and insight; sizes are bytes. Scope expensive scans when possible, for example:
mo analyze --json "$HOME/Library"
Cleanup candidates
mo clean --dry-run prints a summary and writes the candidate paths to:
~/.config/mole/clean-list.txt
Read that file to review the paths this dry-run found. It is a preview snapshot, not an executable deletion plan: a later mo clean rescans and revalidates current candidates, so the two target sets can differ. Never promise the user that the real run will remove exactly this list. purge --dry-run and installer --dry-run report their candidates in the terminal and do not write this list.
Cleanup history
mo history --json --limit N (N is 1-200) returns logs, sessions[], and deletions[]. Use actions.removed, trashed, skipped, and failed to verify the outcome. When failed is nonzero, inspect only the matching session in the operations log and classify permission-protected or running-app paths separately from real cleanup failures.
In Mole 1.59.0+, each session includes an opaque run_id and an attribution: run identifies one run, command groups older command-based records, and ambiguous means older markers cannot distinguish interrupted or overlapping runs. Do not assign ambiguous counts to one run. An empty run_id means no identity was logged; an empty ended_at means no end marker was recorded, not confirmed completion. Each deletion records timestamp, mode, status, size_kb, and path; control bytes in paths appear as \n, \r, \t, or \xHH.
Installed apps
mo uninstall --list prints the app inventory as a JSON array when stdout is not a TTY. Each entry has name, bundle_id, source, uninstall_name, path, and size. Read uninstall_name for the exact argument mo uninstall accepts, so the app selector TUI never has to be opened.
mo uninstall --list
System status
Use mo status --json for a single CPU, memory, disk, and network snapshot. mo status --watch --interval 1s emits NDJSON; collect only the number of samples needed, then terminate it.
Command Notes
mo cleanpermanently removes caches and also sweeps evidence-backed leftovers from already-uninstalled apps. It does not uninstall an installed app.mo uninstallmoves the app and matched leftovers to Trash by default, so they remain recoverable until Trash is emptied.mo clean --external <path>cleans macOS metadata from an external volume; resolve and show the exact mounted path before asking for confirmation.- In current upstream Mole,
mo purgetargets both local build output (target/,build/,dist/,.next/) and dependency directories that require a network to restore (node_modules/,Pods/,venv/,vendor/). A purge is therefore not always recoverable offline: classify the dry-run candidates by recovery type and show that distinction before requesting confirmation. Add--include-emptyto surface zero-size candidates. A non-interactive real run requires an explicit--yes; dry-run does not. Use--yesonly after the user has authorized removal in the current turn. Artifacts with authored content stay protected, and an inconclusive content probe keeps the candidate and reports an incomplete run.mo purge --pathsopens an interactive editor for the scan directories; it is a human surface, so report that the user has to edit it themselves instead of entering it. mo optimizerefreshes caches and system services rather than only deleting files. Explain the planned effects before requesting approval.- Use
--debugonly to diagnose a command that did nothing or failed; normal runs should stay concise.
Upgrade Mole
If Homebrew manages Mole, prefer:
brew upgrade mole
Otherwise, upstream provides mo update. mo update --nightly installs unreleased main; never run it unless the user explicitly requests nightly. After any upgrade, verify the installed version and run a non-destructive smoke test:
mo --version
mo clean --dry-run
Report and Verify
Before cleanup, report the command, potential bytes/items, largest categories, exact risky paths, protected/running-app skips, and the proposed real command. After an approved cleanup:
- Compare free space before and after.
- Read
mo history --json --limit 1. - Explain nonzero
failedand importantskippedcounts without escalating tosudoautomatically. - Verify separately protected paths still exist when the dry-run surfaced dotfiles, login items, Docker data, dependency stores, virtualenvs, or active project state.
A dry-run provides no backup and no undo. Clean deletions are normally permanent, so the preview is the only point at which the user can veto; it is not a way to reverse anything afterwards, and it does not guarantee the real run will target the same set. If a user asks whether Mole removed a specific file, use the deletion log path returned by history and answer from the exact matching record.