Burrow — Developer-First macOS Cleanup

Burrow is a macOS-first command-line tool designed for developers to safely identify and remove unnecessary files left behind by development tools, SDKs, and package managers.

Design Philosophy

• Safety > Aggressiveness: Never delete without explanation.
• Explainable: Tell the user why a file can be safely removed.
• Reversible: Move to trash instead of permanent deletion.
• Zero Telemetry: All operations are local and private.

Commands

burrow scan      # Identify cleanup candidates
burrow clean     # Execute cleanup (dry-run by default)
burrow undo      # Restore last cleanup session
burrow list      # Detailed list of found files
burrow rules     # List all available cleanup rules
burrow stats     # Show disk reclaimable statistics
burrow history   # Show cleanup history and trends
burrow doctor    # Check system health and permissions
burrow version   # Show version information

Advanced Usage

Filter scans by category:

burrow scan --category "Developer Tools"

Filter files by age (e.g., older than 30 days):

burrow scan --older-than 30d

Explain why files are being flagged:

burrow scan --explain

Output results as JSON for automation:

burrow stats --json | jq .

Clean without confirmation (CI/CD mode):

burrow clean --yes

Interactive Selection:

burrow scan --interactive  # or -i

Large File Discovery (scans Downloads, Movies, etc.):

burrow scan --large

History Tracking:

burrow history

Categories Covered

• Package Managers:
  • Node.js: npm (~/.npm), Yarn (~/Library/Caches/Yarn).
  • Python: pip (~/Library/Caches/pip).
  • Rust: Cargo registry & index (~/.cargo).
  • Go: Mod cache (~/go/pkg/mod).
  • Ruby: Gem specs (~/.gem/specs).
  • PHP: Composer (~/.composer/cache).
  • iOS: CocoaPods (~/Library/Caches/CocoaPods).
  • macOS: Homebrew (~/Library/Caches/Homebrew).
• Developer Tools:
  • Xcode: DerivedData, Simulators.
  • Android: Build Cache.
  • Java/Kotlin: Gradle Cache.
  • Go: Build Cache (~/.cache/go-build).
  • JetBrains: Caches (IntelliJ, WebStorm, PyCharm, etc.).
• System:
  • Electron Apps: Cache cleanup for Slack, Discord, VS Code.
  • General user caches and temporary files (/tmp).
• Containers: Docker configuration and usage inspection.
• Large Files: Discovery of files >100MB in common user folders.

Safety Guardrails

Burrow includes hard-coded safety checks to prevent deletion of:

• Paths containing Git metadata (.git).
• System-protected paths (SIP).
• User documents, desktop, and downloads.
• Home directory and root.

Recovery

All deleted files are moved to ~/.burrow/trash/<timestamp>/. You can restore the most recent session using:

burrow undo

Installation

Install directly using Go:

go install github.com/ismailtsdln/burrow/cmd/burrow@latest

Configuration

Customize Burrow by creating ~/.config/burrow/config.json:

{
  "disabled_categories": ["Developer Tools"],
  "excluded_paths": ["/Users/me/important_cache"],
  "size_threshold_mb": 100
}

Custom Rules

You can define your own cleanup rules in ~/.config/burrow/custom_rules.json:

[
  {
    "name": "My Custom Logs",
    "category": "Custom",
    "paths": ["~/Projects/myapp/logs/*.log"],
    "description": "Clean my app's specific logs."
  }
]

Project Structure

• cmd/burrow/: Entry point.
• internal/scanner/: Filesystem traversal logic.
• internal/cleaner/: Trash management and deletion logic.
• internal/rules/: Rules engine and definitions.
• internal/safety/: Hand-blocked safety guardrails.
• internal/ui/: CLI interface and output formatting.