/mole-mac-cleanup

name: mole-mac-cleanup
description: 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 usage; find large files; preview or perform cleanup; remove apps, installers, or project artifacts; diagnose Mole results; or check and upgrade Mole.

Mole Mac Cleanup

Use the official Mole agent skill at `tw93/Mole/skills/mole/SKILL.md` and its `references/macos.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

1. 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. 2. Treat `clean`, `uninstall`, `purge`, `installer`, `slim`, and `optimize` as destructive. Treat `update`, `remove`, and whitelist changes as state-changing and require an explicit request. 3. 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. 4. Never invent flags. Run `mo <command> --help` when the documented surface is insufficient. 5. Preserve Mole's safety layer. Use `mo clean --whitelist` for protected paths; never replace Mole with raw `rm`, hand-written recursive deletion, or broad globs. 6. 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. A cached sudo session can still let `clean` or `optimize` perform system-level work without a new prompt; not invoking `sudo` does not limit the command to user-level cleanup. If that scope is not approved, stop and let the user run the appropriate command themselves. 7. Bound long scans and watches. Send progress updates, stop low-value scans that remain silent, and never leave `mo status --watch` running 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. Current versions also expose `scan_status` at the top level and on entries: `partial` sizes are lower bounds, and `unavailable` means unknown, not zero. Do not report an interrupted or partial scan as complete. 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

Mention in every clean preview that `mo clean` empties `~/.Trash` by default unless the Trash row is protected in the whitelist. 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 t