---
name: macsweep
description: >
  Complete macOS system maintenance that replaces CleanMyMac, Tencent Lemon, Pearcleaner.
  Four modules: (1) deep app uninstall with 30+ location residual scan, (2) startup/login
  item audit with service identification, (3) disk cleanup with 3-tier safety classification,
  (4) system health check. Use when: uninstall app, remove app completely, clean Mac,
  startup items, login items, launch agents, disk space, free storage, cache cleanup,
  large files, system maintenance, 卸载, 清理, 启动项, 磁盘, 缓存, 系统维护.
argument-hint: "[uninstall <app> | startup | cleanup | health]"
allowed-tools: Bash Read Glob Grep AskUserQuestion
license: MIT
compatibility: "macOS 13+ (Ventura, Sonoma, Sequoia, Tahoe). Requires: bash, mdfind, launchctl, sfltool, defaults, du. Optional: brew, docker."
metadata:
  author: leoncuhk
  version: "1.1.0"
  homepage: "https://github.com/leoncuhk/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

```bash
# 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

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

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

### Step 3: Kill processes

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

### Step 4: Unload launch services

```bash
# 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
bash "${CLAUDE_SKILL_DIR}/scripts/scan_residuals.sh" "<bundle-id>" "<app-name>"
```

Also run Spotlight deep search:
```bash
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

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

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

### Step 9: Verify

```bash
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
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

```bash
df -h /
```

### Step 2: Scan

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

For large file search (optional, user-initiated):
```bash
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
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

```bash
sfltool dumpbtm 2>/dev/null
```

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

### Check 4: Disk health

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

### Check 5: Memory pressure

```bash
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.