Macsweep

macsweep

A professional-grade macOS maintenance toolkit invoked via natural language or /macsweep. Replaces GUI tools (CleanMyMac, Tencent Lemon, Pearcleaner) with contextual intelligence — identifies what each file and service actually is, explains impact before acting.

Key metrics: Scans 30+ Library subdirectories (GUI tools check 5-8). Identifies services by inspecting actual binary contents. Manages BTM database directly. Zero runtime overhead.

Safety Principles

1. Never delete without confirmation — present targets with sizes, then ask
2. Scan before act — always run analysis before any destructive operation
3. Trash over rm — prefer osascript -e 'tell app "Finder" to move POSIX file "/path" to trash'; only use rm for system-level files that can't go to Trash
4. Measure before and after — record df -h / baseline, compare after cleanup
5. Explain impact — every deletion recommendation includes "what happens if deleted"
6. Respect sudo boundary — present sudo commands for user to execute, never auto-sudo
7. Verify after cleanup — re-scan to confirm all targets removed
8. Conservative default — when uncertain about a file's purpose, keep it and explain

Absolute Prohibitions

• NEVER rm -rf on /, ~, or any broad wildcard without explicit paths
• NEVER delete SSH keys, GPG keys, .env files, keychains, credentials, or shell configs
• NEVER touch /System, /usr, /bin, /sbin, /Library/Apple
• NEVER delete .git directories without explicit per-repo confirmation
• NEVER auto-execute docker system prune -a — list items individually first
• NEVER skip the scan/analysis step
• NEVER auto-run sudo commands — present them for user to execute

Routing

Parse $ARGUMENTS to select module:

Input Pattern	Module
uninstall <name> or 卸载 <name>	Module 1: App Uninstaller
startup or 启动项	Module 2: Startup Manager
cleanup or 清理	Module 3: Disk Cleanup
health or 健康 or 检查	Module 4: System Health
(empty or ambiguous)	Show module menu, ask user to choose

---

Module 1: Complete App Uninstaller

The most thorough app removal available on macOS — scans 30+ Library subdirectories, manages launch services, and cleans BTM ghost entries.

Step 1: Identify

# Find the app
ls /Applications/ ~/Applications/ 2>/dev/null | grep -i "<name>"
# Extract bundle ID
mdls -name kMDItemCFBundleIdentifier "/Applications/<App>.app"
# Note: also check app's Info.plist for additional identifiers

Store: APP_NAME, BUNDLE_ID, APP_PATH

Step 2: Check if Homebrew-managed

brew list --cask | grep -i "<name>"

If found, prefer brew uninstall --cask <name> — it handles basic cleanup.

Step 3: Kill processes

pgrep -fi "<app-name>"
# If running, ask user to quit. Only force-kill with confirmation:
pkill -fi "<app-name>"

Step 4: Unload launch services

# Scan for related services
launchctl list | grep -i "<bundle-id-or-name>"
ls ~/Library/LaunchAgents/ | grep -i "<bundle-id-or-name>"
ls /Library/LaunchAgents/ 2>/dev/null | grep -i "<bundle-id-or-name>"
ls /Library/LaunchDaemons/ 2>/dev/null | grep -i "<bundle-id-or-name>"

For each match:

• User agents: launchctl bootout gui/$(id -u) <plist-path> then rm <plist>
• System agents/daemons: present sudo launchctl bootout system <plist-path> and sudo rm <plist> for user

Step 5: Remove app bundle

• Homebrew: brew uninstall --cask <name>
• Manual: sudo rm -rf "/Applications/<App>.app" (present to user)

Step 6: Deep residual scan

Scan ALL locations listed in references/residual_locations.md using the bundled script:

bash "${CLAUDE_SKILL_DIR}/scripts/scan_residuals.sh" "<bundle-id>" "<app-name>"

Also run Spotlight deep search:

mdfind "<bundle-id>" -onlyin ~/Library/
mdfind "<app-name>" -onlyin ~/Library/

Present findings as: Location | File/Directory | Size

Step 7: Remove residuals

Delete user-level files directly (with confirmation). Present sudo commands for system-level files.

Step 8: Clean BTM ghost entries

sfltool dumpbtm 2>/dev/null | grep -i "<app-name>"

If ghost entries found: advise sudo sfltool resetbtm + logout/login.

Step 9: Verify

mdfind "<bundle-id>" -onlyin ~/Library/
launchctl list | grep -i "<name>"
ls "/Applications/<App>.app" 2>&1

Confirm all traces removed.

---

Module 2: Startup & Service Manager

Complete visibility into every auto-starting process — identifies what each service does, whether its parent app still exists, and whether it's necessary.

Step 1: Scan all sources

bash "${CLAUDE_SKILL_DIR}/scripts/audit_startup.sh"

Sources scanned:

• ~/Library/LaunchAgents/ — user agents
• /Library/LaunchAgents/ — system agents
• /Library/LaunchDaemons/ — system daemons
• sfltool dumpbtm — BTM database (what System Settings shows)
• launchctl list — currently loaded services

Step 2: Identify each service

For every non-Apple service:

1. Read the plist → find executable path
2. Check if parent app still exists at that path
3. If app exists, inspect its contents to determine purpose (like checking for geoip.dat to identify proxy tools vs legitimate updaters)
4. Classify: Essential / Recommended / Optional / Orphaned / Suspicious

Classification criteria:

• Essential: license verification, security tools, required helpers
• Recommended: auto-update services for apps you actively use
• Optional: sync reporters, telemetry, convenience features
• Orphaned: parent app no longer installed
• Suspicious: unknown developer, unusual executable location, unexpected capabilities

Step 3: Present findings

#	App	Service	Type	Status	Classification	Recommendation

Step 4: Execute changes

Ask user which to disable/remove:

• User agents: launchctl bootout + rm
• System agents/daemons: present sudo commands
• Ghost BTM entries: sudo sfltool resetbtm
• Advise logout/login after BTM reset

---

Module 3: Disk Cleanup

Intelligent cleanup with 3-tier safety classification. Every item shows size and rebuild cost so user can make informed decisions.

Step 1: Baseline

df -h /

Step 2: Scan

bash "${CLAUDE_SKILL_DIR}/scripts/cache_audit.sh"

For large file search (optional, user-initiated):

bash "${CLAUDE_SKILL_DIR}/scripts/find_large_files.sh" 100 "$HOME"

Step 3: Classify and present

Read references/cleanup_targets.md for safety classifications. Present 3 tiers:

SAFE — system caches, old logs, crash reports, Trash, saved app state LOW RISK — old downloads, Xcode DerivedData, Homebrew cache, package manager caches MEDIUM RISK — Docker images/volumes, iOS device support, AI model caches

Each row: Category | Path | Size | Impact If Deleted

Step 4: Execute

• SAFE tier: batch confirm ("Delete all SAFE items? Y/N")
• LOW RISK tier: confirm each category
• MEDIUM RISK tier: confirm each item individually with impact warning

Use Trash where possible. Use brew cleanup for Homebrew. Use specific docker image rm for Docker (never blind docker system prune -a).

Step 5: Report

Before:  XX.X GB available
After:   XX.X GB available
Freed:   XX.X GB
Items cleaned: XX | Items skipped: XX

---

Module 4: System Health Check

Diagnose system issues that accumulate over time.

Check 1: Orphaned app data

Cross-reference installed apps (/Applications/) with ~/Library/Application Support/, ~/Library/Caches/, ~/Library/Preferences/ to find data from uninstalled apps.

Check 2: Broken launch services

Reuse the audit script (which uses PlistBuddy for reliable path extraction):

bash "${CLAUDE_SKILL_DIR}/scripts/audit_startup.sh" 2>&1 | grep "exe_exists=MISSING"

For each MISSING entry, the parent app was uninstalled but the plist was left behind.

Check 3: BTM ghost entries

sfltool dumpbtm 2>/dev/null

Compare BTM entries against installed apps. Flag entries for apps no longer in /Applications/.

Check 4: Disk health

diskutil info / | grep -E "SMART|Health|Type|Free"

Check 5: Memory pressure

memory_pressure -S    # Summary only, no allocation test (fast)
vm_stat | head -10

Note: memory_pressure without -S performs actual memory allocation tests and can take 10-30s.

Present findings with actionable fix for each issue.

---

Anti-Patterns: Think Twice Before Deleting

Target	Size	Why Keep It
Xcode DerivedData	10+ GB	Rebuild costs 10-30 min per project
npm/pnpm cache	5+ GB	Re-download 30min-2hr (network dependent)
~/.cache/uv	10+ GB	Python package cache, slow rebuild
Playwright browsers	3-4 GB	2GB+ re-download each time
iOS DeviceSupport	2-3 GB	Required for on-device debugging
~/.cache/huggingface	varies	AI models, hours to re-download
JetBrains caches	1+ GB	IDE re-indexing takes 5-10 min
Docker stopped containers	<500 MB	May need to restart anytime

Rule: If rebuilding the cache takes longer than the disk space is worth, keep it.

Output Language

Match the user's language. Chinese input → Chinese output. English input → English output.