macos-cleaner
Diagnoses and safely reclaims macOS disk space: caches, logs, app remnants, large/duplicate files, Docker/OrbStack, Chromium code-sign clones, developer caches
Install / Use
npx skills add daymade/claude-code-skills --skill macos-cleanerInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
OperationsSupported Platforms
Our assessment of macos-cleaner
macos-cleaner scores 93/100 on our quality scale, 180th of 746 Operations skills we index (top 25%).
Its SKILL.md is 32 KB long, well organised into 15 sections with 5 code examples: a thorough specification that gives an agent plenty to work with.
With 1,426 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so macos-cleaner is actively maintained.
- Our last check on 2026-10-26 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-04. Automated pattern scan on 2026-10-04. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
macos-cleaner compared with similar skills
All 4 of these similar skills score higher than macos-cleaner; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| macos-cleaner (this skill)by daymade | 93 | 1.4k | 53d ago | SKILL.md |
| x402by browser-use | 100 | 121.0k | 3d ago | SKILL.md |
| algorithmic-artby anthropics | 100 | 177.9k | 55d ago | SKILL.md |
| pptxby anthropics | 100 | 177.9k | 55d ago | SKILL.md |
| designby nextlevelbuilder | 100 | 149.0k | 6d ago | SKILL.md |
Frequently asked questions
- How do I install macos-cleaner?
- Run
npx skills add daymade/claude-code-skills --skill macos-cleaner. The install tabs above show the steps for each supported agent. - Which AI agents does macos-cleaner work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is macos-cleaner safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is macos-cleaner still maintained?
- The repository was last updated about 2 months ago, so macos-cleaner is actively maintained.
Skill content
View source on GitHubname: macos-cleaner description: >- Diagnoses and safely reclaims macOS disk space: caches, logs, app remnants, large/duplicate files, Docker/OrbStack, Chromium code-sign clones, developer caches. Use when a Mac is low on storage, shows “Caching needs more space”, or before deleting anything to avoid data loss. Not for Windows/Linux or permission issues (use macos-permissions).
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 signal | Route |
|---|---|
| Apple Content Caching, AssetCacheManagerUtil, CacheUsed, ActualCacheUsed, iCloud cache, or “Caching needs more space” | Read references/apple_content_caching.md completely before probing or proposing commands |
| Docker, OrbStack, images, containers, or volumes | Read references/docker_analysis.md; inspect every object and never use prune-family commands |
| Docker build cache | Measure with docker builder du; this skill reports it but does not delete it because Docker exposes category-wide prune controls rather than per-record intent |
| Chrome, ChromeDriver, Playwright, Codex Computer Use, Edge, or Chromium has large *.code_sign_clone directories | Read references/chromium_code_sign_clones.md completely; use the bundled analyzer to separate active, inactive, and unknown exact children and never equate du with physical release |
| A named cache, directory, application, or service is already the suspect | Inspect that target first and read the matching semantics in references/cleanup_targets.md; do not start a home-directory or whole-disk scan |
| The user asks what has been growing or filling the disk lately, free space fell between two readings, or an older scan export exists (GrandPerspective text export, saved du output) | Read references/growth_attribution.md; answer with a delta table whose rows name their writer, not a size ranking |
| The source is genuinely unknown | Use the general analysis workflow below; Mole is optional, not the universal first step |
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
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
Avoid broad destructive shell forms. Do not recommend or execute broad
rm -rfor 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. -
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.mdbefore any file deletion. -
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.
-
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
lsofexit 1 with empty output before deciding they are failures. Report the partial state; do not improvise a fallback. -
Before promising physical release from any deletion, name the mechanism — and get it from the creating command, not from a guess. A
dfgap between a nominaldutotal 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 stayunknown— do not substitute the most plausible-sounding mechanism for one you can demonstrate.The mechanisms, distinguished by what
dureports and what deletion releases (all four measured on 2026-09-19, 1 GiB source, drift-controlled):| Created by |
dunominal | Deleting the copy releases | Fingerprint | |---|---|---|---| |cp(bare) /cp -a| full, counted per path | full | independent inodes, independent extents | |cp -c/cp -cR(clonefile) | full, counted per path | ≈0 | different inode,nlink=1, shared extent | |ln/cp -l(hard link) | counted once — sibling reads0| ≈0 | same inode,nlink=2| | local APFS snapshot | full | ≈0 until snapshots are thinned |tmutil listlocalsnapshots /|Two traps this table exists to kill. The clonefile and hard-link rows are opposite on
dubut identical on deletion — both release ≈0, so "deleting it freed nothing" cannot tell them apart, whileducan: a hard-linked sibling counts once (or as0), 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 barecpwhen the folder had been built withcp -cR. Before any deletion, run the probe with the same flags as the creating command. Clonefile is worth flagging as the common case — macOScpdefaults to it for-c, and directories copied for a delivery/kit routinely carry it.
Phase contract
Use this state machine for every cleanup:
- 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.
- 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.
- Execute — approved scope only. Re-read live state immediately before acting, then run each approved command separately and check its exit status and postcondition.
- Verify — independent readback. Measure disk space and subsystem state again, recheck protected services, and observe long enough to detect immediate refill.
Do not compress phases 2 and 3 into one message. A plan printed beside a cleanup command is not a confirmation gate.
Phase 1: read-only diagnosis
Establish the baseline
At minimum, capture:
/bin/date "+%F %T %Z %z"
/usr/sbin/scutil --get ComputerName
/usr/sbin/scutil --get LocalHostName
/usr/bin/sw_vers
/bin/df -k /System/Volumes/Data
/bin/df -h /System/Volumes/Data
Use df -k for calculations and df -h for the human-readable report. Treat an extension, label, or old report as a hint until the live command confirms it.
Establish the success target before an unknown-source scan. Copy a user-supplied free-space or capacity target exactly. If the user supplied none, report the current values and ask for a target in GiB, capacity percentage, or both; do not invent one. A named-suspect diagnosis may continue without a cleanup target, but the ordered unknown-source scan cannot claim a stop condition until the target is explicit.
Keep this first phase read-only. Do not run scripts/cleanup_report.py yet: it creates a local state directory and snapshot file. Preserve the command output in the report instead. On a remote target, always run the direct df commands on that host; the local helper must not measure the controller Mac by mistake.
Follow the named suspect before broad scans
- Query the subsystem's own status and settings.
- Measure physical allocation with a bounded
duon the exact data path only when permissions and user scope allow it. - Distinguish logical content size, sparse-file apparent size, purgeable space, and physically allocated bytes.
- For APFS clones, label
duas path-accounted or nominal rather than physical: shared extents can be attributed to every path, so actual release remains unknown until deletion anddfreadback. - For a suspected growing log, record exact file sizes at two or more timestamps. One large file or one recent mtime does not prove sustained growth.
- Capture the current process, listeners, launch mechanism, and supported health probe of any co-resident service the user marks as critical. Re-resolve PIDs at each checkpoint.
If the known suspect alone can meet the user's free-space target, do not scan unrelated personal or development directories “just in case.”
General analysis when the source is unknown
Run the smallest ordered sequence that can identify enough physical space to meet the target. Stop only when candidates with supported exact actions and defensible expected physical release can meet it. Raw allocation totals, logical cache sizes, shared Docker layers, Trash moves, and unverified “potential savings” do not satisfy the stop condition.
Do not make the physical-confidence ranking hide the user's largest visible hotspot. When a nominal/path-accounted candidate is larger than the recommended action, show both numbers and explain why its physical release is uncertain. Rank by defensible physical release, safety, and effort; report nominal size as a separate column instead of
Truncated for display — read the full file on GitHub.
Related Skills
x402
121.0kSet up Browser Use Cloud payments with x402 — pay per request from a crypto wallet (USDC on Base mainnet), no signup or API key.
algorithmic-art
177.9kCreating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems.
pptx
177.9kUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an em…
design
149.0kComprehensive design skill: brand identity, design tokens, UI styling, logo generation (55 styles, Gemini, Atlas Cloud, or MuAPI AI), corporate identity program (50 deliverables, CIP mockups), HTML presentations (Chart.js), banner design (22 styles, social/ads/web/print), icon design (15 styles, SVG…
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
