macOS Cleaner

macOS Cleaner

Diagnose the actual source of disk pressure, reclaim only approved space, and prove that the cleanup did not damage user data or co-resident services.

Entry router

Choose the narrowest path that can answer the request:

User-provided scope exclusions override every generic scan suggestion. Do not inspect personal directories, credentials, databases, application state, or unrelated services when the user excludes them.

Safety and authorization contract

1. Separate observation from mutation. Complete a read-only diagnosis first. Do not delete, stop a service, edit settings, install or upgrade tools, or run a cleanup preview that may mutate state during that phase.
2. Confirm the exact target. On a remote Mac, record the current host identity before any other work. Never infer the machine from an IP, old PID, directory name, or prior report.
3. Plan before asking. Before any state change, list every command, what it changes, expected physical space reclaimed, impact, recoverability, and postconditions. Then stop if the user requested a plan-only phase.
4. Require explicit approval. If the user supplies an exact confirmation phrase, require that phrase. Otherwise ask for unmistakable approval of the listed commands and targets. Approval for one plan does not authorize a fallback or a wider cleanup.
5. Use precise supported controls — and check them for known defects first. Prefer an application's supported cache-management command or an exact object ID. "Official" and "precise" are not evidence of safety, so before the first supported-control command runs, do a known-issue check on that exact command at the installed version: a search of the tool's issue tracker for the command name, plus its changelog for fixes landing in a later release than the one installed. A command with an open, version-relevant defect is not a supported control for this skill — treat it like the category-wide commands in the next rule and either upgrade past the fix or use an exact-path alternative. If no supported control exists, an exact application-owned cache directory may be removed only after verifying its owner, confirming the application is stopped or the directory is otherwise inactive, explaining rebuild/redownload impact, and receiving approval. Never target a broad cache root or active application state.
6. Never use Docker prune-family commands. This includes image, container, volume, system, builder, and buildx prune. Category-wide deletion cannot express per-object user intent.
7. Avoid broad destructive shell forms. Do not recommend or execute broad rm -rf or glob deletion. For exact approved ordinary files, prefer Finder Trash. The bundled legacy helper permanently deletes and has only the limited guards documented below; never treat it as equivalent to Trash.
8. Preserve valuable state. Never target user documents, credentials, SSH material, active databases, application configuration, or running-service state merely to increase the reported savings. Read references/safety_rules.md before any file deletion.
9. Execution follows the user's authorization. If the user asks only for analysis or wants to run commands personally, hand off the commands. If the user asks the agent to fix the machine and explicitly confirms the scoped plan, execute the exact approved commands and verify them. Unattended recurring deletion logic needs separate approval before it is written or enabled.
10. Fail fast. An unexpected non-zero command, a mismatched postcondition, an unexpected target, or a changed dependency stops the cleanup. Interpret documented probe statuses such as lsof exit 1 with empty output before deciding they are failures. Report the partial state; do not improvise a fallback.
11. Before promising physical release from any deletion, name the mechanism — and get it from the creating command, not from a guess. A df gap between a nominal du total and actual reclaim means one candidate mechanism is at work, and the strongest evidence is the verbatim command that created the folder, because the copy verb alone decides the space semantics. Find it in session history before theorizing; a folder-name or size-based inference is not a mechanism. Only if no command can be found does the gap stay unknown — do not substitute the most plausible-sounding mechanism for one you can demonstrate.

The mechanisms, distinguished by what du reports and what deletion releases (all four measured on 2026-09-19, 1 GiB source, drift-controlled):

Two traps this table exists to kill. The clonefile and hard-link rows are opposite on `du` but identical on deletion — both release ≈0, so "deleting it freed nothing" cannot tell them apart, while du can: a hard-linked sibling counts once (or as 0), a clonefile copy counts full. And calibrating the wrong copy verb proves nothing: a 98 GiB gap was twice attributed to the wrong mechanism because the probe used bare cp when the folder had been built with cp -cR. Before any deletion, run the probe with the same flags as the creating command. Clonefile is worth flagging as the common case — macOS cp defaults to it for -c, and directories copied for a delivery/kit routinely carry it.

Phase contract

Use this state machine for every cleanup:

1. Observe — read-only. Capture identity, disk baseline, the suspected subsystem's status and configuration, physical allocation, and critical-service health.

1b. Authorize stateful inspection when unavoidable. If deeper evidence requires creating a temporary container, pulling an image, mounting a volume, or writing a snapshot, first finish the metadata-only observation, list the exact inspection commands and their side effects, and obtain separate approval. Inspection approval is not cleanup approval.

1. Plan — no mutation. Pass the Phase 2 entry gate first (four steps: target confirmation, classification table, gate rules, checker — see below), then explain findings, commands, impact, recovery, expected release, and success criteria. Stop at the confirmation gate.