🧹 MacSweep

The only Mac cleanup tool that understands AI tools.
Free. Open source. Zero telemetry. 100% local.

Why • Differentiators • Install • Usage • Dashboard • Config • Contribute

💡 Why MacSweep

Your Mac fills up. You install Ollama, pull a few models, and suddenly 26 GB is gone. You try Cursor, Claude Desktop, Trae, Antigravity — each leaves gigabytes of cache, logs, and orphaned model blobs when you uninstall.

No cleanup tool on the market knows about any of this.

CleanMyMac charges $90/year to clean your caches. It doesn't touch Ollama. It doesn't find Claude Desktop cache. It has no idea OpenCode exists.

MacSweep does. It's one bash script, 523 lines, zero dependencies, and it's free forever.

🎯 What Makes It Different

TL;DR — Everyone cleans ~/Library/Caches. We clean the 10 GB of AI model blobs, IDE caches, and container images that nobody else touches.

🤖 AI-Aware Cleanup (unique) The only tool that knows about modern AI developer tools: Ollama — Model blobs (with --deep safety) Claude Desktop — Application cache Cursor — IDE cache OpenCode — Session logs Gemini CLI — Local cache Trae / Antigravity / Blackbox — Full uninstall of abandoned tools Detects and removes orphaned AI configs from uninstalled apps	🔒 Privacy by Design Zero telemetry. Ever. Audit the 523-line script yourself. 100% local. No cloud, no account, no analytics. No network calls. Not even for updates. Config in plain YAML at ~/.config/macsweep/config.yaml History in plain JSON — your data stays yours. Runs entirely offline.
⚡ Zero Dependencies Pure bash. No Node, no Python, no Electron. 523 lines, auditable in one sitting. Works out of the box on any macOS 12+. Install in 10 seconds with one curl command. Uninstall cleanly — it's just one script.	🛡️ Safety First --dry-run shows everything before deleting. Docker detection — skips Docker data if running. Deep mode gated — destructive ops require --deep + confirmation. Age-based cleanup — only deletes DMGs older than 30 days. Per-module toggles — disable anything you don't trust. No sudo required — only touches your home directory.
🖥️ CLI + Dashboard CLI for power users — scriptable, schedulable, silent mode. Web dashboard with 4 panels: Dashboard, Modules, Schedule, History. Single-file HTML — no build step, opens anywhere. Responsive down to 375px. Keyboard accessible, WCAG-aware.	🔄 Automation Built-In LaunchAgent for scheduled cleanups (daily/weekly/monthly). Silent mode for unattended cron jobs. Native macOS notifications on completion. Module-level targeting — clean only what you want. Exit codes for CI/CD pipelines.

Head-to-head

	MacSweep	CleanMyMac X	OnyX	DaisyDisk
Price	🟢 Free forever	🔴 $90/year	🟢 Free	🟡 $10
Open source	🟢 MIT	🔴	🔴	🔴
Ollama models	🟢 Yes	🔴	🔴	🔴
Claude Desktop cache	🟢 Yes	🔴	🔴	🔴
Cursor / OpenCode / Gemini	🟢 Yes	🔴	🔴	🔴
Orphaned AI tool cleanup	🟢 Yes	🔴	🔴	🔴
Docker/Podman aware	🟢 Yes	🟡 Basic	🔴	🔴
Zero telemetry	🟢 Audited	🔴	🟢	🟢
CLI scriptable	🟢 Yes	🔴	🔴	🔴
Dry-run mode	🟢 Yes	🔴	🔴	🔴
Dashboard UI	🟢 Yes	🟢	🟡	🟢
Runtime dependencies	🟢 None	🔴 App	🔴 App	🔴 App
Scheduled automation	🟢 LaunchAgent	🟢	🔴	🔴

Real numbers from a developer Mac

System Caches         5.2 GB   ████████
Browser Caches        3.1 GB   █████
Dev Tools (npm/Xcode) 2.8 GB   █████
Containers           17.0 GB   ████████████████████████
AI Tools             26.0 GB   ██████████████████████████████████
                     ─────────
Total reclaimed      54.1 GB   🔥

Without the AI module, 48 % of reclaimed space would be invisible to traditional cleaners.

📸 Screenshots

Modules Panel	Schedule Panel
History Panel	Responsive (375px)

📦 Installation

Quick install (recommended)

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/royaluniondesign-sys/MacSweep/main/install.sh)"

That's it. No Homebrew tap. No Node. No account.

Manual install

git clone https://github.com/royaluniondesign-sys/MacSweep.git
cd MacSweep
./install.sh

What the installer does

1. Copies cli/macsweep.sh to /usr/local/bin/macsweep
2. Creates ~/.config/macsweep/ with default config.yaml
3. Copies the dashboard to ~/.config/macsweep/dashboard/
4. Does NOT install any LaunchAgent unless you run macsweep --schedule
5. Does NOT require sudo (installs to /usr/local/bin only if writable, otherwise ~/.local/bin)

Verify install

macsweep --version
# → MacSweep v1.0.0

Uninstall

rm /usr/local/bin/macsweep
rm -rf ~/.config/macsweep
launchctl unload ~/Library/LaunchAgents/com.macsweep.daemon.plist 2>/dev/null
rm ~/Library/LaunchAgents/com.macsweep.daemon.plist 2>/dev/null

Done. Nothing else touches your system.

🚀 Usage

60-second tour

# See what would be cleaned (safe, no deletion)
macsweep --dry-run

# Show disk analysis only
macsweep --analyze

# Interactive cleanup (asks before each risky step)
macsweep

# Silent automation
macsweep --auto --silent

# Clean only AI tools and dev caches
macsweep --modules=ai,dev --auto

# Deep clean (includes Ollama models, Docker data)
macsweep --deep

All commands

Command	Description
macsweep	Interactive cleanup with confirmations
macsweep --auto / -a	Skip confirmations, run everything
macsweep --deep / -d	Deep clean — includes Ollama, Docker
macsweep --dry-run	Preview without deleting
macsweep --analyze	Disk analysis only
macsweep --modules=LIST	Run specific modules (comma-separated)
macsweep --silent / -s	No output — for cron/LaunchAgent
macsweep --ui	Open the dashboard
macsweep --version / -v	Show version
macsweep --help / -h	Show help

Available modules

Module	What it cleans	Typical size
caches	~/Library/Caches, ~/.cache, logs > 7 days	5–15 GB
browsers	Chrome, Brave, Safari, Firefox, Arc	2–10 GB
dev	npm, pip, Homebrew, Xcode DerivedData	3–10 GB
ai 🤖	Ollama, Claude, Cursor, OpenCode, Gemini	10–50 GB
containers	Docker (if stopped), Podman	5–30 GB
duplicates	*copy*, * 2.ext, .DS_Store	0.1–2 GB
downloads	Old DMGs (30d), PKGs (30d), ZIPs (60d)	1–5 GB

Examples

# Weekly scheduled cleanup (via LaunchAgent)
macsweep --auto --silent

# Only reclaim AI disk space, preview first
macsweep --modules=ai --dry-run
macsweep --modules=ai --deep

# Analyze disk, then decide
macsweep --analyze

# CI/CD: fail pipeline if cleanup finds nothing to do
macsweep --auto --silent && echo "cleaned" || exit 1

🖥️ Dashboard

Open with macsweep --ui or directly in your browser: ~/.config/macsweep/dashboard/index.html

4 panels, all data persisted in localStorage:

• Dashboard — Disk ring, KPI cards, cleanup activity chart, recent runs
• Modules — Toggle the 7 cleanup modules, see estimated reclaim
• Schedule — Enable auto-cleanup, set frequency/time, toggle notifications
• History — Filter past runs (auto / manual), see trend sparklines

Tech: React 18 + Tailwind CDN, single standalone HTML file. No build step. No server required.

⚙️ Configuration

Location

~/.config/macsweep/
├── config.yaml     # Your settings
├── history.json    # Cleanup history
└── logs/
    └── macsweep_YYYYMMDD.log

Default config

version: 1

modules:
  system_caches: true
  browser_caches: true
  dev_tools:     true
  ai_tools:      true
  containers:    true
  duplicates:    true
  downloads:     true

schedule:
  enabled:   false
  frequency: weekly      # daily | weekly | monthly
  day:       sunday      # for weekly
  time:      "03:00"

notifications:
  enabled:                 true
  disk_warning_threshold:  90   # percent

deep_clean:
  ollama_models: false   # requires --deep flag
  docker_reset:  false

exclude:
  paths:
    - ~/Documents/Important
  extensions:
    - .important

Environment variables

Variable	Effect
MACSWEEP_AUTO=1	Skip confirmations
MACSWEEP_DEEP=1	Enable deep clean
MACSWEEP_SILENT=1	No output
MACSWEEP_CONFIG=path	Use custom config file

🧹 What Gets Cleaned (exact paths)

System Caches — 5–15 GB typical

~/Library/Caches/*
~/.cache/*
~/Library/Logs/*.log   (older than 7 days)

Browser Caches — 2–10 GB typical

Chrome:  ~/Library/Caches/Google/Chrome/*
Brave:   ~/Library/Caches/BraveSoftware/*
Safari:  ~/Library/Caches/com.apple.Safari/*
Firefox: ~/Library/Caches/Firefox/*
Arc:     ~/Library/Caches/Arc/*

AI Tools 🤖 — 10–50 GB typical (unique to MacSweep)

Ollama:      ~/.ollama/models/blobs/*        (with --deep only)
Claude:      ~/Library/Application Support/Claude/Cache/*
Cursor:      ~/.cursor/Cache/*
OpenCode:    ~/.local/share/opencode/log/*
Gemini:      ~/.gemini/cache/*
Trae:        ~/.trae, ~/Library/Application Support/Trae
Antigravity: ~/.antigravity, ~/Library/Application Support/Antigravity
Blackbox:    ~/.blackbox*, ~/Library/Application Support/BLACKBOXAI
Codex:       ~/.codex

Dev Tools — 3–10 GB typical

npm:      ~/.npm/_cacache/*, ~/.npm/_logs/*
pip:      ~/Library/Caches/pip/*
Homebrew: brew cleanup -s
Xcode:    ~/Library/Developer/Xcode/DerivedData/*

Containers — 5–30 GB typical

Podman: ~/.local/share/containers/*
Docker: ~/Library/Containers/com.docker.docker/Data/vms/0/data/*
        (only if Docker is NOT running, requires --deep)

Duplicates & Downloads

Desktop: *copy*, *Copy*, * 2.*
Home:    .DS_Store (recursive)
Downloads: *.dmg (>30 days), *.pkg (>30 days), *.zip (>60 days)

⏰ Scheduling Automation

MacSweep ships a LaunchAgent template you can enable with one command:

# Enable weekly cleanup, Sundays at 3 AM
macsweep --schedule=weekly --time=03:00

# Disable
macsweep --schedule=off

Under the hood, this writes ~/Library/LaunchAgents/com.macsweep.daemon.plist and loads it with launchctl. No background process runs unless scheduled.

🛡️ Safety Model

MacSweep is aggressive by design but never destructive by accident:

Safeguard	How it works
Dry run	--dry-run shows every action without executing
Module gating	Destructive ops (Ollama, Docker) require --deep
Running detection	Skips Docker cleanup if Docker is running
Age gates	Downloads cleanup only touches files > 30/60 days
Home-only	Never touches /System, /Library (root), or /Applications
No sudo	Cannot escalate privileges
Audit log	Every cleanup writes to ~/.config/macsweep/logs/
Dry by default	First run always prompts before cleaning

What MacSweep will NEVER do:

• ❌ Touch /System, /private, or SIP-protected paths
• ❌ Delete anything in /Applications
• ❌ Modify user documents, photos, or media
• ❌ Run with sudo or request root
• ❌ Send any data over the network
• ❌ Install anything beyond a single bash script

📁 Project Structure

MacSweep/
├── cli/
│   └── macsweep.sh          # Main CLI (523 lines bash, no deps)
├── web-ui/
│   └── index.html           # Dashboard (React + Tailwind, standalone)
├── daemon/
│   └── com.macsweep.plist   # LaunchAgent template
├── docs/
│   ├── screenshot-dashboard.png
│   ├── screenshot-modules.png
│   ├── screenshot-schedule.png
│   ├── screenshot-history.png
│   └── screenshot-mobile.png
├── install.sh               # One-line installer
├── LICENSE                  # MIT
└── README.md

🔧 Development

Requirements

• macOS 12+
• Bash 3.2+ (ships with macOS)
• A browser (for the dashboard)

That's it. No Node, no Python, no build tools.

Running locally

# CLI — just run the script
./cli/macsweep.sh --dry-run

# Dashboard — open the file directly, or serve it
python3 -m http.server 8742 --directory web-ui
open http://localhost:8742

Testing safely

# Safe sandbox: only dry-run
./cli/macsweep.sh --dry-run

# Test a single module
./cli/macsweep.sh --modules=duplicates --dry-run

Releasing

git tag v1.0.1
git push origin v1.0.1
# GitHub Actions (future) will attach the tarball

🗺️ Roadmap

• CLI with 7 cleanup modules
• AI-aware cleanup (Ollama, Claude, Cursor, OpenCode, Gemini)
• Dashboard UI (4 panels, responsive)
• Dry-run + safety gates
• LaunchAgent scheduling
• Homebrew formula — brew install macsweep
• Native macOS menubar app (SwiftUI)
• iCloud sync for multi-Mac config
• More AI modules: GitHub Copilot, JetBrains AI, Zed
• Disk usage prediction ("you'll be full in 12 days")
• Webhook notifications (Slack, Discord)
• uninstall.sh for clean removal

🤝 Contributing

Contributions are very welcome. Good first issues:

• Add a new AI tool module (use module_ai() as a template)
• Add a browser (e.g. Zen, Orion)
• Improve dry-run output formatting
• Add tests (bats-core is already pulled in)
• Translate the dashboard UI
• Test on Apple Silicon vs Intel

Workflow

1. Fork the repo
2. Create a branch: git checkout -b feat/my-feature
3. Commit using Conventional Commits: feat: add Zed cache module
4. Open a PR against main
5. One maintainer review + CI green → merge

Code style

• Bash follows Google Shell Style Guide
• JavaScript/JSX follows Prettier defaults
• No emojis in code, only in CLI output and docs
• Keep the CLI under 1,000 lines total

❓ FAQ

Is this safe to run on my production machine?

Yes. MacSweep only touches your home directory, never /System, and supports --dry-run to preview everything. The default mode asks before every destructive action. Deep mode (Ollama/Docker) requires an explicit --deep flag.

Will I lose my Ollama models?

Only if you pass --deep. Without it, the AI module cleans logs and caches but leaves model blobs intact. With --deep, you'll be asked for confirmation unless --auto is also set.

How is this different from `brew cleanup`?

brew cleanup only touches Homebrew. MacSweep cleans 7 categories across 20+ tools, including AI tools and browsers Homebrew doesn't know about.

Does it work on Apple Silicon?

Yes. MacSweep is pure bash — it runs identically on Intel and Apple Silicon.

Can I use it in CI/CD?

Yes. Use --silent --auto for no output, and check exit codes. Example for GitHub Actions runners on self-hosted Macs:

- name: Free disk space
  run: macsweep --auto --silent --modules=caches,dev,containers

Does it phone home?

No. Zero network calls. Audit the script — it's 523 lines, you'll see every curl, wget, nc (there are none).

Can I contribute a Windows/Linux port?

Yes, please! Open an issue first so we can coordinate naming (linuxsweep?) and shared module logic.

📜 License

MIT — see LICENSE. Do whatever you want with it.

🙏 Credits

Built with the philosophy: zero recurring costs, full local control.

Created by RUD Agency • Designed in dark mode.

_{⭐ If MacSweep reclaimed gigabytes for you, star the repo ⭐}

_{Made with 🧹 and a lot of reclaimed disk space.
MacSweep • v1.0.0 • MIT License • © 2026 RUD Agency}