macsweep

Complete macOS system maintenance as a Claude Code skill. Replaces CleanMyMac, Tencent Lemon, Pearcleaner, and similar GUI tools — with zero runtime overhead.

No app to install. No daemon running. No subscription. Just invoke when needed.

What it does

Module	Command	Capability
App Uninstaller	/macsweep uninstall <app>	Deep uninstall scanning 30+ Library locations + Spotlight + BTM cleanup
Startup Manager	/macsweep startup	Audit all LaunchAgents/Daemons, identify each service's purpose, manage BTM
Disk Cleanup	/macsweep cleanup	3-tier safety classification, 40+ cache types, before/after reporting
Health Check	/macsweep health	Orphaned app data, broken services, ghost BTM entries, disk health

Or just describe what you need in natural language — the skill auto-triggers on keywords like "uninstall", "cleanup", "startup items", "disk space", etc.

Why not a GUI tool?

	GUI Tools	macsweep
Residual scan depth	5-8 locations	30+ locations + Spotlight deep search
Service identification	Shows name only	Inspects binary contents to determine actual purpose
BTM management	Cannot access	Direct sfltool integration
Runtime overhead	Always-on daemon, menu bar icon, memory usage	Zero — invoked on demand
Transparency	Black box deletion	Explains every action before executing
Safety	Fixed rules	Contextual intelligence — understands rebuild cost vs disk savings
Cost	$30-90/year subscription	Free and open source

Install

One-command install

npx skills add leoncuhk/macsweep

Manual install

git clone https://github.com/leoncuhk/macsweep.git
cp -r macsweep ~/.claude/skills/

Via Homebrew (coming soon)

brew install --cask macsweep  # planned

Usage examples

Uninstall an app completely:

> /macsweep uninstall "Tencent Lemon"

Scanning 30+ locations for com.tencent.Lemon...
Found 12 residual items (3 LaunchDaemons, 6 Preferences, 2 Caches, 1 Application Scripts)
Total size: 24.3 MB

Proceed with cleanup? [Y/n]

Audit startup items:

> /macsweep startup

| # | App              | Service              | Type   | Status   | Classification |
|---|------------------|----------------------|--------|----------|----------------|
| 1 | Google Chrome    | GoogleUpdater.wake   | agent  | loaded   | Recommended    |
| 2 | Baidu Netdisk    | netdisk_service      | agent  | disabled | Optional       |
| 3 | Microsoft Office | update.agent         | agent  | loaded   | Recommended    |
| 4 | (Unknown)        | SparkleService       | daemon | loaded   | Suspicious     |

Clean disk space:

> /macsweep cleanup

Before: 45.2 GB available

SAFE (batch confirm):
  - System caches: 2.1 GB
  - Old logs: 340 MB
  - Crash reports: 120 MB
  - Trash: 944 MB

LOW RISK (individual confirm):
  - npm cache: 2.8 GB
  - uv cache: 4.6 GB
  - Homebrew cache: 624 MB

After: 56.7 GB available | Freed: 11.5 GB

Architecture

macsweep/
├── SKILL.md                  # Main skill instructions (311 lines)
├── scripts/
│   ├── scan_residuals.sh     # 30+ location deep residual scanner
│   ├── audit_startup.sh      # LaunchAgents/Daemons/BTM auditor
│   ├── cache_audit.sh        # 40+ cache type size analyzer
│   └── find_large_files.sh   # Large file finder with categorization
├── references/
│   ├── residual_locations.md # Complete Library subdirectory reference
│   └── cleanup_targets.md   # Safety-classified cleanup guide
├── README.md
└── LICENSE

Safety

• Never deletes without confirmation — always shows what will be deleted with sizes
• Trash over rm — prefers moving to Trash over permanent deletion
• Respects sudo boundary — presents system-level commands for user to execute
• Conservative defaults — when uncertain, keeps the file and explains why
• Anti-pattern awareness — warns against deleting caches that cost more time to rebuild than disk space they save (Xcode DerivedData, HuggingFace models, npm cache, etc.)
• NEVER DELETE list — SSH keys, GPG keys, .env files, keychains, system paths are absolutely protected

Requirements

• macOS 13+ (Ventura, Sonoma, Sequoia, Tahoe)
• Claude Code (or any agent supporting the Agent Skills standard)
• Built-in tools: bash, mdfind, launchctl, sfltool, defaults, du
• Optional: brew (for Homebrew-managed app detection), docker (for container cleanup)

Compatibility

macsweep follows the Agent Skills open standard and works with:

• Claude Code
• Cursor
• GitHub Copilot
• OpenAI Codex
• Gemini CLI
• Roo Code
• Kiro
• And 30+ other compatible agents

License

MIT

Contributing

Issues and PRs welcome. Please test on your own machine before submitting changes to cleanup logic — we take the safety-first principle seriously.