tidymymac

README

🧹 TidyMyMac

An open-source macOS storage cleanup utility for developers.
Scan, review, and reclaim disk space — safely, transparently, and from the terminal.

✨ Features

• 🖥️ Interactive TUI to browse and select what to clean
• 🛡️ Dry-run by default — nothing is deleted without your explicit confirmation
• 🔌 Modular cleaners for different categories of junk
• 📊 Progress reporting and summary of reclaimed space
• 📤 Export scan results as JSON or CSV
• 📝 Generate shell cleanup scripts from scan results
• 🎯 Target specific categories in any command

🗂️ Cleaners

Category	What it targets
🗑️ Temporary Files	/tmp, /var/tmp, user temp directories
📦 Application Caches	~/Library/Caches
📋 System Logs	~/Library/Logs, /Library/Logs, /var/log
🍺 Homebrew Cache	Packages cached by brew
🐳 Docker Artifacts	Stopped containers, untagged images, orphaned volumes
📱 iOS Backups	iPhone/iPad backups in ~/Library/Application Support/MobileSync/Backup
🍎 macOS Updates	Old macOS update residues and installers
🗂️ Xcode	DerivedData, archives, simulators
👨‍💻 Development Artifacts	Go build cache and downloaded module cache
🕰️ Time Machine Snapshots	Local Time Machine snapshots stored on disk
🗑️ Trash	Files in the Trash waiting to be permanently removed

🚀 Installation

# Clone and build
git clone https://github.com/viniciussouzao/tidymymac
cd tidymymac
make build

# Run
./bin/tidymymac

Requires Go 1.21+

🛠️ Usage

# Launch interactive TUI (dry-run, nothing is deleted)
tidymymac

# Actually delete the selected files
tidymymac --execute

📋 Commands

scan — identify junk without deleting

# Interactive table (default)
tidymymac scan

# Scan specific categories only
tidymymac scan docker caches xcode

# Output as JSON or CSV
tidymymac scan --output json
tidymymac scan --output csv

# Include individual file paths in output
tidymymac scan --output json --detailed

# Save output to a timestamped file
tidymymac scan --output csv --save

# Generate a shell cleanup script from scan results
tidymymac scan --generate-script

# Suppress progress output (useful in scripts)
tidymymac scan --output json --quiet

clean — delete junk files

# Preview what would be deleted (dry-run, default)
tidymymac clean

# Actually delete files
tidymymac clean --execute

# Clean specific categories
tidymymac clean docker caches --execute

# Use a previously saved detailed scan instead of re-scanning
tidymymac clean --from-file scan.json --execute

# Output cleanup result as JSON
tidymymac clean --output json

Other commands

tidymymac version   # Print version, commit, build date, platform, and Go version
tidymymac explain   # Explain what each category contains
tidymymac history   # Show past cleanup runs

🏗️ Development

make build   # Compile binary to bin/tidymymac
make test    # Run tests with race detection
make run     # Build and run
make clean   # Remove build artifacts

🔒 Safety

TidyMyMac is designed with safety as the primary concern:

• ✅ Dry-run by default: scanning and reviewing never touches your files
• ✅ Explicit confirmation required: deletion only happens with --execute
• ✅ No silent operations: every file is shown before removal
• ✅ Errors are non-fatal: a failure on one file won't stop the rest

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.