MAccleaN

A safe, dev-focused macOS disk cleanup tool — with a web dashboard UI and a .app you can pin to the Dock.

Reclaims space from regenerable caches and build artifacts only. It never touches your source code, documents, or keychains.

---

Features

• Dry-run by default — reports sizes, deletes nothing unless you pass --apply
• Web dashboard — visual card grid sorted by biggest offender, click to select, clean from browser
• macOS .app — double-click from Finder or pin to Dock, no Terminal needed
• Root cause visible — stacked bar chart + "Biggest offender" label so you know what to fix first
• Large file finder — finds files >200 MB in Downloads, Movies, Desktop, Documents
• Old downloads scan — files in ~/Downloads not modified in 6+ months
• Move to Trash, not delete — file-list categories use macOS Trash for safe recovery
• Xcode Archives protected — reported but never auto-deleted (not regenerable)
• Zero dependencies — Python 3 (ships with macOS) + bash only

---

---

What it cleans

Category	What	Safe to delete?
xcode-derived	Xcode DerivedData — build intermediates	✅ Fully regenerable
xcode-devicesupport	OS symbols for old device versions	✅ Re-downloaded on connect
xcode-archives	Release builds + dSYMs	⚠️ Reported only, never deleted
simulators	CoreSimulator caches + unavailable devices	✅ Regenerable
cocoapods	CocoaPods source cache	✅ Re-fetched on pod install
gradle	Android dependency cache	✅ Re-downloaded on build
metro	React Native Metro + Watchman caches	✅ Regenerated on next bundle
pnpm	pnpm content store (unreferenced packages)	✅ Prune-safe
npm	npm package cache	✅ Safe to clear
yarn	Yarn package cache	✅ Safe to clear
brew	Homebrew old versions + download cache	✅ brew cleanup
large-files	Files >200 MB in common directories	🗑️ Moved to Trash
old-downloads	~/Downloads files not modified in 6+ months	🗑️ Moved to Trash
user-caches	~/Library/Caches (aggressive mode only)	⚠️ Aggressive
trash	~/.Trash (aggressive mode only)	⚠️ Aggressive

---

Quick start

git clone https://github.com/your-username/macclean.git
cd macclean
chmod +x macclean.sh

# Report only — safe, nothing deleted
./macclean.sh

# Open web dashboard (browser opens automatically)
./macclean.sh --serve

---

Web dashboard

./macclean.sh --serve
# → http://localhost:7420

• Cards sorted by size (biggest offender first)
• Stacked bar chart shows space breakdown at a glance
• Click cards to select, "Clean Selected" to free space
• For large-files / old-downloads: click "▾ View files" to inspect before cleaning
• Log panel streams real-time output during cleanup
• Rescan button refreshes without reloading

---

Desktop app

Build a double-clickable .app from the scripts:

./build_app.sh

This creates macclean.app in the current directory. Install it:

cp -r macclean.app /Applications/

Then open from Finder, Spotlight, or pin to Dock. Double-clicking while already running just opens the browser.

Rebuild after updates: Re-run ./build_app.sh after editing macclean.sh or macclean_server.py.

---

CLI reference

./macclean.sh                            # dry-run: report sizes only
./macclean.sh --apply                    # delete, prompts before each category
./macclean.sh --apply --yes              # delete, no prompts
./macclean.sh --apply --only xcode-derived,gradle,npm
./macclean.sh --apply --aggressive       # also clears ~/Library/Caches and Trash
./macclean.sh --list                     # print category names and exit
./macclean.sh --serve                    # launch web dashboard

Dry-run (default)

Running without flags prints sizes and a total — nothing is deleted:

MAccleaN — dev macOS cleanup
Mode: DRY-RUN  (report only — nothing will be deleted)

▸ Xcode DerivedData (build intermediates — fully regenerable)
  DerivedData               15.1 GB  ~/Library/Developer/Xcode/DerivedData

▸ Gradle cache
  Gradle caches              7.3 GB  ~/.gradle/caches

...

Total reclaimable: 45.0 GB

Targeted cleanup

# Only Xcode caches
./macclean.sh --apply --only xcode-derived,xcode-devicesupport,simulators

# Only JS ecosystem
./macclean.sh --apply --only npm,yarn,pnpm,metro

---

Requirements

• macOS 12 Monterey or later
• Python 3 (pre-installed on macOS, or via Homebrew)
• bash (pre-installed)

No pip install required.

---

Safety model

MAccleaN is designed to be safe by default:

1. Dry-run by default. Without --apply, nothing is ever deleted.
2. safe_rm guard. Refuses to delete blank, /, or $HOME paths.
3. Archives never deleted. Xcode Archives are reported for awareness but MAccleaN will not touch them.
4. Trash instead of delete. Large-files and old-downloads categories move files to ~/.Trash so they can be recovered.
5. Aggressive mode is opt-in. ~/Library/Caches and ~/.Trash are only included with --aggressive.

---

Files

macclean.sh          # CLI cleanup tool
macclean_server.py   # Python 3 web server (zero external deps)
build_app.sh         # Builds macclean.app

---

Contributing

MAccleaN is free and always will be. If it saved you disk space, consider making it better for everyone.

Pull requests are welcome — the goal is a tool that's genuinely useful without needing a subscription or an app store. Some ideas if you want to contribute:

• New categories — Docker images, Android AVDs, VS Code extensions cache, pip/Poetry, rbenv/pyenv old versions
• Better UI — dark/light toggle, per-file selection for large-files scan, last-cleaned timestamp
• macOS app polish — menu bar icon, system tray with "idle / running" status, auto-launch at login
• Performance — parallel scanning, faster du alternatives, incremental rescan
• Cross-project detection — find node_modules / .build directories inside project folders
• Bug fixes and edge cases — network volumes, APFS snapshots, permissions errors

To get started:

git clone https://github.com/your-username/macclean.git
cd macclean

# Make changes to macclean.sh or macclean_server.py
# Test with:
./macclean.sh          # CLI dry-run
./macclean.sh --serve  # Web dashboard

# Rebuild the app bundle after changes:
./build_app.sh

Open a pull request with a short description of what you changed and why. No CLA, no process overhead.

---

License

MIT

---

Buy me a coffee

If MAccleaN saved you some disk space, consider sending a token — any EVM-compatible chain works.

ERC-20 address:

0x34aB30c0433B57Dfa7c7E687d6e276FE7C77AeD0

Accepts ETH, USDC, USDT, or any ERC-20 token on Ethereum, Base, Arbitrum, Polygon, etc.