macOS Disk Space Diagnostic Tool — AI-first CLI, JSON by default
Slimmer scans your Mac for space-consuming directories that may contain unused, temporary, or reclaimable files. It produces structured JSON reports with severity ratings, cleanup rationale, and risk assessments — perfect for piping into AI agents, scripts, or dashboards.
Slimmer is 100% safe. It NEVER deletes, modifies, or moves any files.
Slimmer is a read-only diagnostic tool. It walks directories, measures sizes, and reports findings — nothing more. There are no
--force,--clean, or--deleteflags. No file system writes of any kind. You can run it on any Mac without risk.
- 100% safe — strictly read-only, no file system writes, no delete commands, no risk
- 38 built-in scan rules covering caches, dev tools, package managers, browsers, logs, and more
- JSON-first output — machine-readable by default, ideal for AI agents and automation
- Human-readable mode — color-coded terminal output with
--format text - Parallel scanning — uses Rayon for fast multi-threaded directory walking
- Severity ratings — INFO, LOW, MEDIUM, HIGH, CRITICAL based on size thresholds
- Composable filters — by category, rule ID, severity, and sort order
cargo build --release
alias slimmer=./target/release/slimmer
# Full scan → JSON to stdout (default)
slimmer scan
# Pipe to jq — top 3 space consumers
slimmer scan --top 3 | jq '.results[] | {name, total_bytes, severity}'
# Filter: only developer tools, high+ severity
slimmer scan --category developer --min-severity high
# Specific rule
slimmer scan --rule-id xcode_derived_data
# Sort by severity instead of size
slimmer scan --sort-by severity
# Compact single-line JSON (for piping to AI tools)
slimmer --compact scan
# Human-readable colored output
slimmer --format text scan
# Save JSON to file while also printing
slimmer scan --output report.json
# List all scan rules
slimmer rules
slimmer rules --dev-only
slimmer rules --category browser
# Quick summary (no per-location details)
slimmer summary
# End-user only (no dev locations)
slimmer --no-dev scan| Command | Description |
|---|---|
slimmer scan |
Full diagnostic scan with per-location details |
slimmer rules |
List all scan rules with metadata |
slimmer summary |
Quick overview — totals by category and severity |
| # | Location | Category | Target |
|---|---|---|---|
| 1 | ~/Library/Caches |
System Cache | All users |
| 2 | ~/Library/Developer/Xcode/DerivedData |
Developer | Xcode builds |
| 3 | ~/Library/Developer/Xcode/iOS DeviceSupport |
Developer | Debug symbols |
| 4 | ~/Library/Developer/CoreSimulator |
Developer | iOS Simulators |
| 5 | ~/Library/Containers/com.docker.docker |
Containers | Docker images |
| 6 | ~/.npm |
Package Manager | npm cache |
| 7 | ~/.cargo/registry |
Package Manager | Rust crates |
| 8 | ~/Library/Caches/pip |
Package Manager | Python packages |
| 9 | ~/Library/Caches/Homebrew |
Package Manager | Brew bottles |
| 10 | ~/.gradle/caches |
Package Manager | Java/Android |
| 11 | ~/Library/Application Support/MobileSync/Backup |
Backups | iOS backups |
| 12 | ~/Library/Logs |
Logs | App/system logs |
| 13 | ~/.Trash |
Miscellaneous | Deleted files |
| 14 | ~/Downloads |
Miscellaneous | Old downloads |
| 15 | ~/Library/Caches/Google/Chrome |
Browser | Chrome cache |
| 16 | ~/Library/Application Support/Slack |
Messaging | Slack data |
| 17 | ~/Library/Mail |
Apple Mail | |
| 18 | ~/.m2/repository |
Package Manager | Maven artifacts |
| 19 | ~/Library/Caches/Yarn |
Package Manager | Yarn cache |
| 20 | ~/Library/Caches/CocoaPods |
Package Manager | CocoaPods |
| ... | and 18 more locations |
Run slimmer rules for the full list with descriptions.
{
"total_rules": 38,
"rules": [
{
"id": "xcode_derived_data",
"name": "Xcode DerivedData",
"description": "...",
"category": "DeveloperTools",
"base_severity": "High",
"path_pattern": "~/Library/Developer/Xcode/DerivedData",
"recursive": true,
"developer_only": true,
"cleanup_rationale": "...",
"risk_note": "...",
"size_threshold_upgrade_bytes": 10737418240
}
]
}{
"generated_at": "...",
"hostname": "...",
"disk_total_bytes": 1000000000000,
"disk_used_bytes": 750000000000,
"disk_available_bytes": 250000000000,
"total_reclaimable_bytes": 45000000000,
"locations_found": 15,
"total_files": 125000,
"by_category": [...],
"by_severity": [...],
"scan_duration_ms": 1200
}docker compose run test # Build + run all tests
docker compose run demo # Run against simulated macOS home
docker compose run demo-json # JSON outputsrc/
├── main.rs # CLI (clap subcommands, JSON-first output)
├── scanner/
│ ├── types.rs # Data model (ScanRule, ScanResult, DiagnosticReport)
│ └── engine.rs # Core scanner (parallel dir walking, size calc)
├── rules/
│ ├── definitions.rs # All 38 scan rules with metadata
│ └── registry.rs # Rule filtering and lookup
└── report/
├── formatter.rs # Rich terminal output (--format text)
└── json_report.rs # JSON file export
tests/
└── integration_test.rs # End-to-end CLI tests
- Fork the repository
- Create your feature branch (
git checkout -b feature/my-feature) - Run tests:
cargo test - Commit your changes
- Open a Pull Request
MIT
{ "generated_at": "2025-01-15 14:30:00 UTC", "hostname": "macbook-pro", "home_dir": "/Users/dev", "disk_total_bytes": 1000000000000, "disk_used_bytes": 750000000000, "disk_available_bytes": 250000000000, "total_reclaimable_bytes": 45000000000, "total_scan_duration_ms": 1200, "results": [ { "rule_id": "xcode_derived_data", "name": "Xcode DerivedData", "description": "Xcode build intermediates...", "path": "/Users/dev/Library/Developer/Xcode/DerivedData", "exists": true, "total_bytes": 25000000000, "file_count": 50000, "dir_count": 3000, "largest_files": [["/path/to/big.o", 500000000]], "category": "DeveloperTools", "severity": "Critical", "cleanup_rationale": "Rebuilt automatically when you open a project.", "risk_note": "Next build will be a full rebuild.", "developer_only": true, "newest_file_modified": "2025-01-15 14:00:00", "oldest_file_modified": "2024-06-01 09:00:00", "scan_duration_ms": 300 } ], "category_summary": [...], "severity_summary": [...] }