macbroom — macOS Cleanup Tool

Scan for reclaimable disk space:

!macbroom scan 2>&1 || echo "macbroom not installed — brew install lu-zhengda/tap/macbroom"

Analyze the scan results above. Present a summary of reclaimable space by category. Then ask which categories to clean, or if the user wants to clean all. Use macbroom clean --dry-run first to preview, then macbroom clean to execute.

Commands

Command	Purpose	Example
macbroom scan	Scan for reclaimable space	macbroom scan
macbroom scan --<category>	Scan specific category	macbroom scan --xcode --docker
macbroom scan --threshold N	Only show items above size threshold	macbroom scan --threshold 100M
macbroom clean	Clean scanned junk files	macbroom clean --dry-run
macbroom clean --permanent	Delete permanently (skip Trash)	macbroom clean --permanent -y
macbroom uninstall <app>	Fully uninstall app + related files	macbroom uninstall Slack
macbroom maintain	Run system maintenance tasks	macbroom maintain
macbroom spacelens [path]	Visualize disk space usage	macbroom spacelens ~ --depth 3
macbroom spacelens -i	Interactive disk space explorer	macbroom spacelens -i
macbroom dupes [dirs...]	Find duplicate files	macbroom dupes ~/Documents
macbroom stats	Show cleanup history	macbroom stats
macbroom report	Cleanup history report	macbroom report
macbroom watch	Monitor free disk space	macbroom watch --free 10G
macbroom schedule enable	Enable scheduled cleaning	macbroom schedule enable
macbroom schedule disable	Disable scheduled cleaning	macbroom schedule disable
macbroom schedule status	Show schedule status	macbroom schedule status
macbroom trends	Storage usage trends from snapshots	macbroom trends --last 30d
macbroom trends --forecast	Predict when disk will fill up	macbroom trends --forecast
macbroom trends record	Capture storage snapshot (for lanchr agent)	macbroom trends record

Storage Trends

Track storage usage over time and forecast disk capacity:

# View storage usage trends
macbroom trends

# Filter to last 30 days
macbroom trends --last 30d

# Predict when disk will fill up
macbroom trends --forecast

# Capture a storage snapshot (for periodic recording via lanchr agent)
macbroom trends record

# JSON output for scripting
macbroom trends --json

Combine with lanchr create --template monitor-disk to automatically record storage snapshots and alert on predicted disk full dates.

Size Filtering

Filter scan results to only show items above a threshold:

# Only items larger than 100 MB
macbroom scan --threshold 100M

# Combine with category
macbroom scan --docker --threshold 500M

Disk Space Monitoring

Watch free disk space and alert when it drops below a threshold:

# Alert when free space drops below 10 GB
macbroom watch --free 10G

Combine with lanchr create --template monitor-disk for persistent disk monitoring.

Cleanup Reports

View cleanup history and trends:

macbroom report

Shows total space reclaimed, cleanup frequency, and category breakdown over time.

JSON Output

Add --json to any read command for machine-readable output:

macbroom scan --json
macbroom dupes ~/Documents --json
macbroom stats --json
macbroom spacelens ~ --json
macbroom report --json
macbroom trends --json
macbroom trends --forecast --json

Scanner Categories

Use category flags with scan or clean:

Flag	What it scans
--system	System caches, logs, temp files
--browser	Browser caches and data
--xcode	Derived data, archives, simulators
--large	Large files (configurable threshold)
--docker	Docker images, containers, volumes
--node	node_modules, npm/yarn cache
--homebrew	Homebrew cache, old versions
--simulator	iOS Simulator data
--python	pip cache, pycache, venvs
--rust	Cargo cache, target directories
--go	Go module cache, build cache
--jetbrains	JetBrains IDE caches and logs

No flags = scan all categories.

Safety Guidelines

• Always scan before clean: macbroom scan first to review what will be removed
• Use --dry-run: macbroom clean --dry-run shows what would be deleted without deleting
• Default goes to Trash: Files go to Trash unless --permanent is specified
• Backup important data: Especially before uninstall or dupes cleanup

TUI Mode

Launch macbroom without arguments for interactive cleanup with category selection and preview.