macleanse

An Agent Skill that performs a CleanMyMac-style deep scan of macOS storage and helps you reclaim space safely. Designed to be invoked from any skills-compatible agent (Claude Code, Claude Desktop, Cursor, OpenCode, Codex, and 50+ more) whenever you say things like "clean my Mac", "disk full", "Mac is slow", or "free up space".

Why

CleanMyMac costs ~$90/year. OnyX is free but cryptic. Manual cleanup with du, find, rm is doable but tedious — and easy to get wrong.

macleanse gives Claude a structured workflow for the same job: scan → classify by risk → propose actions → confirm → report. The skill never auto-deletes user data; destructive scripts default to dry-run.

Install

Recommended — via the skills CLI (works for any skills-compatible agent)

npx skills add igornumeriano/macleanse -g -y

The CLI auto-detects which agents you have installed (Claude Code, Cursor, OpenCode, Codex, …) and installs the skill globally for all of them. To target a specific agent:

npx skills add igornumeriano/macleanse -g -a claude-code -y

Run npx skills add igornumeriano/macleanse --list first if you want to inspect before installing.

Alternative — manual clone

git clone https://github.com/igornumeriano/macleanse.git ~/.claude/skills/macleanse
chmod +x ~/.claude/skills/macleanse/scripts/*.sh

Claude Code picks up skills from ~/.claude/skills/ automatically. Restart Claude or reload skills if needed.

Usage

The skill triggers on natural-language requests. From Claude Code or Claude Desktop:

"Clean my Mac"

"My disk is full, what's eating the space?"

"System Data is huge, help me reduce it"

"Mac is slow, do a housekeeping pass"

Claude will run the analysis, classify findings into three risk levels, and walk you through cleanup with confirmation at each step.

You can also run the scripts directly:

# Read-only deep scan (deletes nothing)
bash ~/.claude/skills/macleanse/scripts/analyze.sh

# Quick scan (skips slow file-system traversals)
bash ~/.claude/skills/macleanse/scripts/analyze.sh --quick

# Safe cleanup — recreatable caches only — defaults to dry-run
bash ~/.claude/skills/macleanse/scripts/safe_clean.sh
bash ~/.claude/skills/macleanse/scripts/safe_clean.sh --apply

# Thin APFS local Time Machine snapshots (often 10-100GB hidden)
bash ~/.claude/skills/macleanse/scripts/thin_snapshots.sh

# Find leftovers from uninstalled apps
bash ~/.claude/skills/macleanse/scripts/find_leftovers.sh

# Run macOS maintenance tasks (interactive picker)
bash ~/.claude/skills/macleanse/scripts/maintenance.sh

What it covers

Risk	Categories
🟢 Safe	System & app caches (Chrome, Safari, Spotify, Discord, Adobe, VSCode, Slack, etc.), logs, diagnostic reports, Saved Application State, font/icon/QuickLook caches, lock files, .DS_Store, Trash
🟡 Dev	npm / yarn / pnpm / CocoaPods / Homebrew / pip / Cargo / Go module caches; Xcode DerivedData / Archives / iOS DeviceSupport / CoreSimulator; orphaned node_modules; .next / .turbo / dist; __pycache__; APFS local snapshots; Docker; Android Studio AVDs
🔴 User data	Downloads (old, duplicates, lock files, installers); iOS backups; Mail / iMessage attachments; WhatsApp media (in-app only); application leftovers; archived projects; large files in home
🩺 Health	Memory pressure, swap usage, top processes, login items, launch agents, SIP / FileVault status, APFS containers, filesystem verify
🔧 Maintenance	BSD periodic scripts, DNS flush, Spotlight reindex, font cache rebuild, memory purge

See references/categories.md for the full path/command reference.

Safety

• All destructive scripts default to dry-run. Pass --apply to actually delete.
• Sizes are shown before any deletion.
• A strict denylist (references/never_touch.md) lists paths the skill must never touch — Photo Library, iCloud Drive, Keychains, 1Password vaults, iOS backups (without explicit confirmation), ~/Library/Mobile Documents, _CodeSignature, etc.
• An allowlist (references/safe_paths.md) lists known-safe paths.
• The skill prefers archiving (move to Dropbox/iCloud/external drive) over deleting for any user data.

Layout

macleanse/
├── SKILL.md              # workflow + philosophy (loaded into Claude's context)
├── scripts/
│   ├── analyze.sh        # read-only deep scan
│   ├── safe_clean.sh     # 🟢 cleanup; --dry-run by default
│   ├── thin_snapshots.sh # APFS local snapshots (interactive)
│   ├── find_leftovers.sh # orphan hunter
│   └── maintenance.sh    # macOS maintenance tasks
└── references/
    ├── categories.md     # commands per category
    ├── safe_paths.md     # allowlist
    └── never_touch.md    # denylist

Compatibility

• macOS only (Darwin). Tested on macOS 15 (Sequoia). Should work on 12+ (Monterey).
• Pure bash — no external dependencies.
• Uses tmutil, diskutil, csrutil, fdesetup, osascript, defaults — all built into macOS.

License

MIT — see LICENSE.

Contributing

Issues and PRs welcome. If you find a path that should be added to safe_paths.md or never_touch.md, please open an issue with the rationale.