macsweep

CleanMyMac for your terminal — reclaim disk space and tame memory on macOS, from the command line. Free, open source, no subscription, no telemetry, no bloatware.

🚀 Quick Start

npm install -g macsweep
macsweep

Requires Node ≥ 20.12 (Node 20 LTS or 22 recommended; avoid the 21.x line).

🎬 Demo

💡 Why macsweep

| | macsweep | Typical paid GUI cleaner | |---|---|---| | Price | Free & open source | Subscription | | Deep browser cleaning | Per profile & cache type (Chrome/Brave/Edge/Chromium/Arc) | Often one lumped "cache" | | Docker cleanup | Per type (images, build cache, containers, dangling volumes opt-in) | Rarely covered | | Memory insight | ram report + safe renderer end | GUI-only, gated | | Undo | 30-day backup & restore | Varies | | Privacy | 100% offline, no telemetry | Often phones home | | Runs in CI/scripts | macsweep run --json | No |

✨ Features

| Feature | Description | |---------|-------------| | 🚀 One Command | Just run macsweep — no complex setup | | 🎯 Interactive | Select exactly what you want to clean | | 📁 File Explorer | Drill down (→) into categories to select specific folders/files | | 🛡️ Safe by Default | Risky items hidden unless you use --risky | | 🔍 Smart Scanning | Finds caches, logs, dev files, browser data, and more | | 📱 App Uninstaller | Remove apps completely with all associated files | | 🔧 Maintenance | Flush DNS cache, free purgeable space, prune Time Machine snapshots | | 🔒 Privacy First | 100% offline — no data ever leaves your machine | | 💾 Backup-by-Default | Moderate/risky items are backed up automatically before deletion | | ↩ 30-Day Undo | Restore any clean within 30 days with macsweep restore | | 🔎 Dry Run | Preview what would be freed without deleting anything (-d) | | 🌐 Deep Browser Clean | Chromium-family browsers cleaned per profile and per cache type (HTTP, Code, GPU, WebGPU, Shader, Service Worker) — cookies/logins/history never touched | | 🐳 Per-Type Docker Clean | Dangling images, build cache, stopped containers each cleaned separately; dangling volumes opt-in via --docker-volumes | | 🧠 Memory Report | macsweep ram shows what's using RAM (Chrome, Docker, system) with What/Why/How; --kill safely ends Chrome renderers |

🎯 What It Cleans

🟢 Safe (always safe to delete)

| Category | What it cleans | |----------|---------------| | trash | Files in the Trash bin | | temp-files | Temporary files in /tmp and /var/folders | | browser-cache | Chrome, Brave, Edge, Chromium, Arc: cleaned deeply per user profile and cache type (HTTP, Code, GPU, WebGPU, Shader, Service Worker storage). Each item explains what it is and what removing it affects. Service Worker storage removal prevents web apps from working offline. Cookies, logins, history, and bookmarks are never enumerated or removed. Firefox and Safari remain at summary level. | | homebrew | Homebrew download cache | | docker | Unused Docker images, containers, build cache, and volumes. Docker cleanup now lists each reclaimable type separately (dangling images, stopped containers, build cache, dangling volumes), each explaining what it is and what removing it affects. Dangling volumes are off by default (removing them can delete database and persistent data) and only cleaned when explicitly opted in with --docker-volumes. Cleanup runs the narrow prune for exactly the selected types instead of a lumped docker system prune. |

🟡 Moderate (generally safe)

| Category | What it cleans | |----------|---------------| | system-cache | Application caches in ~/Library/Caches | | system-logs | System and application logs | | dev-cache | npm, yarn, pip, Xcode DerivedData, CocoaPods | | node-modules | Orphaned node_modules in old projects |

🔴 Risky (use --risky flag)

| Category | What it cleans | |----------|---------------| | downloads | Downloads older than 30 days | | ios-backups | iPhone and iPad backup files | | mail-attachments | Downloaded email attachments | | duplicates | Duplicate files (keeps newest) | | large-files | Files larger than 500MB | | language-files | Unused language localizations |

📖 Usage

# Interactive mode — scan, select, and clean
macsweep

# Preview what would be cleaned without deleting anything
macsweep --dry-run

# Include risky categories
macsweep --risky

# Enable file picker for all categories
macsweep --risky -f

Backup-by-default: When you run a real clean, macsweep automatically backs up all moderate/risky items before deleting them. Backups are kept for 30 days, giving you a full undo window. Pass --no-backup to skip backing up if you want to delete immediately without keeping a copy.

Non-Interactive (Scripts / CI)

Use macsweep run for scripted or automated cleanups — no prompts, no progress output. --categories is required. Without --yes the command only previews what would be removed.

# Preview what would be freed (nothing is deleted)
macsweep run --categories trash,system-cache

# Actually delete
macsweep run --categories trash,system-cache --yes

# Include risky categories, machine-readable output
macsweep run --categories downloads --risky --yes --json

run Flags

    --categories <list>  Comma-separated category ids to clean (required)
-y, --yes                Actually delete (omit to preview only)
-d, --dry-run            Preview without deleting (same effect as omitting --yes; states intent explicitly)
-r, --risky              Include risky categories
    --no-backup          Skip backing up moderate/risky items before deleting
    --docker-volumes     Opt into pruning dangling Docker volumes (off by default; removing them can delete database/persistent data)
    --json               Emit a machine-readable JSON result to stdout; logs/warnings go to stderr

Exit Codes (run)

| Code | Meaning | |------|---------| | 0 | Success | | 1 | One or more clean errors | | 2 | Bad usage (missing or invalid --categories) |

JSON Output (--json)

Only the JSON envelope is written to stdout (pipe-safe). Logs and warnings go to stderr. The envelope includes schemaVersion: 1. Cross-volume items that cannot be backed up are skipped (not deleted) and reported in skipped.crossVolume; risky categories requested without --risky appear in skipped.risky.

Folder-Level Selection (Interactive)

Press → on supported categories to drill into specific folders/files:

• ↑↓ navigate • ← back • → enter • space select • a all • i invert • o reveal in Finder • ⏎ submit

Uninstall Apps

macsweep uninstall

Maintenance Tasks

macsweep maintenance --dns          # Flush DNS cache (may require sudo)
macsweep maintenance --purgeable    # Free purgeable space
macsweep maintenance --timemachine  # Delete local Time Machine snapshots

Restore (Undo a Clean)

Backups are kept for 30 days. Use the restore command to undo a previous clean:

macsweep restore --list      # Show available backups (newest first)
macsweep restore --last      # Undo the most recent clean
macsweep restore <id>        # Restore a specific backup by id

Memory Report

macsweep ram

A read-only memory report showing what is using RAM on your system. It lists:

• Chrome processes — broken down per process (tabs, extensions, utilities), each explaining what it is and why it's using memory. The main Chrome process is never marked for action.
• Docker containers — each running container and what it's consuming, so you can decide which to stop or restart.
• System inactive memory — memory cached by the OS that can be freed if needed.

Each item explains What (what is it), Why (why is it using memory), and How (how much). The command never kills processes or purges memory — it reports and guides only, so you can decide what to do.

Safe Renderer End (Interactive Mode)

macsweep ram --kill

Interactive mode to end selected Chrome renderer and helper processes via SIGTERM (Chrome reloads those tabs — no tab loss, no logout). The main Chrome process is never offered for termination. Each kill re-validates the PID is still that Chrome helper before ending it (recycled-PID guard). A confirmation is required before any process is ended. Plain macsweep ram (without --kill) remains read-only.

Other Commands

macsweep categories          # List all available categories
macsweep config --init       # Create a config file
macsweep config --show       # Show current config
macsweep backup --list       # List backups
macsweep backup --clean      # Remove old backups (older than the configured retention window)

Flags

-V, --version          Show version number
-h, --help             Show help
-r, --risky            Include risky categories
-f, --file-picker      Force file picker for ALL categories
-A, --absolute-paths   Show absolute paths
-d, --dry-run          Preview what would be cleaned without deleting anything
    --no-backup        Skip backing up moderate/risky items before deleting
    --docker-volumes   Opt into pruning dangling Docker volumes (off by default; removing them can delete database/persistent data)
    --no-progress      Disable progress bars

🔒 Security

| | | |---|---| | ✅ Open Source | All code publicly available for audit | | ✅ No Network | Operates 100% offline | | ✅ No Root Required | All operations run as current user (except opt-in maintenance) | | ✅ Protected Paths | Hard blocklist prevents touching system-critical paths | | ✅ TOCTOU-safe deletion | Re-checks symlinks immediately before deletion | | ✅ Backup-by-default | Moderate/risky items are moved to ~/.macsweep/backups before deletion and kept for 30 days | | ✅ Cross-volume guard | Items on a different volume than ~/.macsweep cannot be backed up via rename; macsweep warns and requires explicit second confirmation before permanently deleting them |

🗺️ Roadmap

• [ ] More scanners — Slack/Discord/Spotify cache, iOS Simulator, Photos cache, etc.
• [ ] Scheduling — automatic cleanups on a schedule (launchd) with notifications.
• [ ] History & reporting — persist runs, export JSON/HTML reports, track reclaimed space over time.

🛠️ Development

git clone https://github.com/tuanphansy/macsweep.git
cd macsweep
bun install
bun run dev        # Run in dev mode
bun run test       # Run tests
bun run lint       # Run linter
bun run typecheck  # Type-check
bun run build      # Build for production

Build and lint require Node ≥ 20.12 with util.styleText — use Node 20 LTS or 22 (the 21.x line lacks it and will crash bun run build/bun run lint).

🙏 Credits

Built on the foundation of mac-cleaner-cli by @guhcostan (MIT), then substantially extended with deep browser/Docker cleaning, memory tooling, backup/restore, and a scriptable run command.

📄 License

MIT — see LICENSE.