Buildingmac-sweep:AFastmacOSCleanupCLIinPython

Every developer's Mac eventually becomes a digital hoarder. Gigabytes of node_modules graveyards, stale Xcode derived data, abandoned pip caches, three generations of iOS simulator runtimes — it all adds up.

I wanted a single command that would honestly audit the mess, let me review it, and clean it safely. After not finding quite what I was looking for, I built mac-sweep — a fast, beautiful, and safety-first CLI tool for macOS.

The Problem

Most cleanup tools either:

• Delete things without telling you what they're deleting (dangerous)
• Show you a wall of text with no structure (useless)
• Lock real features behind a subscription (annoying)

I wanted something with the honesty of a dry-run flag, the clarity of a well-designed table, and the safety of a rollback manifest.

Design Principles

Three rules guided every decision:

1. Preview before you commit. Every destructive operation supports --dry-run.
2. Risk transparency. Each scan target is labelled Safe: ✓ (auto-regenerated by the OS) or Safe: ! (may contain data you care about).
3. Reversibility. When cleaning in --delete-mode trash, mac-sweep writes a rollback manifest to ~/.mac_sweep/manifests/ so you can restore items later.

What It Scans

mac-sweep knows about 20+ junk locations across 9 categories:

The Commands

scan — survey the damage

mac-sweep scan
mac-sweep scan --category cache package dev
mac-sweep scan --top 10 --age-days 30
mac-sweep scan --json   # pipe-friendly output

Outputs a sorted table: location, size, safety rating, age. Sorted by size so the biggest offenders are always at the top.

clean — interactive deletion

mac-sweep clean                      # prompts for each location
mac-sweep clean --safe-only --yes    # fully automatic safe clean
mac-sweep clean --dry-run            # preview only
mac-sweep clean --risk-level safe --delete-mode trash

Each run writes a rollback manifest so nothing is truly gone unless you empty the trash.

large — hunt down space hogs

mac-sweep large                 # files > 100 MB in home
mac-sweep large --min-mb 500   # raise the threshold
mac-sweep large --path ~/Movies

Useful when a rogue video export or VM snapshot is eating your disk.

doctor — quick health snapshot

mac-sweep doctor

Shows disk usage %, macOS version, Homebrew outdated package count, Trash size, and total cache size — in under a second.

restore — undo a cleanup

mac-sweep restore --list
mac-sweep restore --manifest ~/.mac_sweep/manifests/cleanup-20260320-143200.json

Implementation Notes

The project is organised as a proper Python package:

macsweep/
├── __main__.py       # python -m macsweep entrypoint
├── cli.py            # argparse routing
├── config.py         # scan targets, risk config
├── utils.py          # size helpers, Rich rendering, JSON
└── commands/
    ├── scan.py
    ├── clean.py
    ├── large.py
    ├── doctor.py
    └── restore.py

A few things worth calling out:

Rich for output. The Rich library makes the tables and progress indicators look great. It degrades gracefully if Rich isn't installed — falling back to plain text.

JSON mode everywhere. Every command supports --json for scripting. Useful for cron jobs that log cleanup results or pipe into jq.

Rollback manifests. When you use --delete-mode trash, mac-sweep records a JSON manifest with every moved path so restore can put things back without guesswork.

Install

git clone https://github.com/Rahul-Sahani04/mac-sweep
cd mac-sweep
bash install.sh   # sets up .venv and installs to /usr/local/bin

Then just run:

mac-sweep scan

What's Next

A few things I'm thinking about adding:

• Scheduled clean profiles — define a safe set of targets and run them weekly via launchd
• Homebrew integration — surface outdated packages inside doctor
• Interactive TUI — a Textual interface for browsing scan results

If any of that sounds useful to you, PRs are welcome.