Using Mole from an agent

Mole (mo) cleans, uninstalls, analyzes, optimizes, and monitors a Mac. It is a real deletion tool operating on someone's live machine, so the way an agent uses it differs from the way a human does: never guess, never let a TUI decide, and never let a destructive command run without the user having seen the list.

Workflow

1. Inspect. Check mo --version, relevant command help, and df -h for the source and destination volumes. Start with mo analyze --json "$HOME", then inspect only the large relevant subdirectories. Put options before the path: some installed versions launch the TUI for mo analyze <path> --json. Report partial or unavailable scans as incomplete. A directory's logical size, especially a mounted container or a symlink, is not proof of internal disk usage. Do not add parent and child sizes together.
2. Classify. Separate rebuildable caches, installed runtimes, persistent app data, backups, and credentials. A directory called cache may contain an active browser executable or an interpreter used by another process.
3. Preview cleanup. Apply the rules below. Preserve existing whitelist entries and the installed defaults when saving a custom whitelist. Check both path aliases and resolved targets against active runtimes, browser profiles, agent sessions, models, and container data. Native tool settings can redirect cleanup outside the directory a wrapper checks; the whitelist is not a filesystem sandbox. Regenerate the preview after protection or configuration changes, and stop if protected data remains a candidate.
4. Relocate only when requested. Read Storage relocation before moving caches, configuring future writes, or moving an app's data. Cleanup permission does not authorize arbitrary data migration or new startup/periodic tasks.
5. Verify and report. Check actual free space again, then the affected tool or app using isolated fixtures where possible. Distinguish copied, verified, app switched, and source retired. An original still on the source disk has not released that space. Report retained originals, deferred active caches, restart requirements, and external-disk dependencies. Stop when only trivial new caches remain; do not repeatedly sweep the Mac.

The rules

1. Preview before you delete. Always. Check the installed command's help and run its supported --dry-run. Read the result and show the user what would go before offering the real run. If no usable preview is available, stop rather than delete blindly. Running mo clean before mo clean --dry-run skips the user's chance to exclude data.
2. The user runs the destructive command, not you, unless they explicitly asked you to do it in the current turn. "Clean my Mac" is such an ask; "why is my disk full" is not.
3. Never parse a TUI frame. Interactive mo analyze and terminal-attached mo status are full-screen Go programs whose output is drawn, not printed. Use mo analyze --json, mo status --json, or mo status --watch instead.
4. Never invent flags. The command surface is small and listed here; if something is not on this page, run mo <command> --help and read it, do not assume a --yes or --force exists.
5. Protection is a whitelist, not an argument. If the user wants a cache kept, the answer is mo clean --whitelist, not a hand-rolled find. Never work around Mole's safety layer with raw rm.

What answers which question

Machine-readable surfaces

These four surfaces are the agent-facing API. Everything else is for humans.

Disk usage. mo analyze --json prints one JSON object: path, overview, and entries[] of {name, path, size, is_dir, insight}. size is bytes. insight: true marks an entry Mole considers noteworthy (a large iOS backup, a runaway cache). Pass a path to scope it: mo analyze --json "$HOME/Library". When present, inspect scan_status at both the root and entry level.

Cleanup history. mo history --json [--limit N] (N is 1-200) prints logs (paths of the operations and deletions logs) plus sessions[] with command, started_at, items, size, and an actions breakdown of removed / trashed / skipped / failed. This is how you answer "did Mole delete my file" without guessing: the deletions log has the paths.

The dry-run path list. mo clean --dry-run prints a summary to the terminal and writes every candidate path to ~/.config/mole/clean-list.txt. Read that file, not the terminal output, when you need to reason about or show the user exactly what a real run would remove. This list is clean-only: mo purge --dry-run and mo installer --dry-run print their candidates to the terminal and write no file.

System status. mo status --json prints one metrics snapshot. It also switches to JSON automatically when stdout is not a TTY, but pass --json explicitly in scripts so intent stays obvious. mo status --watch --interval 1s emits one complete JSON object per line from a warm collector. Bound the watch duration or sample count and terminate it after collecting the evidence the user asked for; do not leave an unbounded monitor running in the background.

Command notes worth knowing

• mo clean also sweeps leftovers from apps the user already deleted. It does not touch installed apps; that is mo uninstall.
• mo clean --external <path> cleans macOS metadata off an external volume; it does not relocate caches or app data.
• mo purge removes rebuildable project artifacts: local build output (target/, build/, dist/, .next/) and dependency directories that need a network to restore (node_modules/, Pods/, venv/, vendor/). A purge is therefore not always recoverable offline, so say which kind the candidates are before running it. mo purge --paths configures which directories are scanned; --include-empty shows zero-size candidates.
• mo optimize refreshes caches and system services. It is the one destructive command whose effects are not "files disappear", so say what it will do before running it.
• mo update self-updates; mo update --nightly installs unreleased main. Do not run either on a user's behalf without being asked.
• --debug on any command prints the detailed operation log. Reach for it when a command silently did nothing; do not leave it on in normal use.

When something goes wrong

mo clean deletions are permanent by default. Cache cleanup removes files rather than moving them to the Trash, so there is usually nothing to restore. That is why rule 1 exists: exclude data during preview, before deletion. mo uninstall is the exception: it routes the app and its leftovers through the Trash, so an uninstalled app is recoverable until the Trash is emptied.

What you do have is a record. mo history --json names the deletions log, and every deletion is one tab-separated line in it: timestamp, mode, size, status, path. So when a user asks "did Mole take my file", read the log and answer with the actual line instead of guessing. Then add the path to the whitelist (mo clean --whitelist) so the next run leaves it alone.