Reclaim disk space across macOS and Linux. One command, 13 specialized cleaners, zero guesswork.
Your dev machine accumulates gigabytes of stale data: old Nix generations, Go build caches, Docker images, Homebrew downloads, pnpm/pnpm/yarn/bun caches, Gradle/Maven artifacts, Xcode DerivedData, temp files, and more.
Clean Wizard finds and removes all of it — safely, with dry-run previews, confirmation dialogs, and protected generations.
Reclaim 5-20 GB in seconds.
Note: Clean Wizard uses
encoding/json/v2. SetGOEXPERIMENT=jsonv2before building.
GOEXPERIMENT=jsonv2 go install github.com/LarsArtmann/clean-wizard@latestOr build from source:
git clone https://github.com/LarsArtmann/clean-wizard.git
cd clean-wizard
GOEXPERIMENT=jsonv2 go build -o clean-wizard ./cmd/clean-wizard/Or use the Nix devShell (sets GOEXPERIMENT automatically):
nix develop
go build -o clean-wizard ./cmd/clean-wizard/# Interactive TUI — pick what to clean
clean-wizard clean
# Quick daily cleanup (safe, no system-level operations)
clean-wizard clean --mode quick
# Preview without changing anything
clean-wizard clean --dry-run
# JSON output for scripts and CI
clean-wizard clean --json| Cleaner | What It Cleans | Platforms |
|---|---|---|
| Nix | Old generations, garbage collection | Linux |
| Homebrew | Cache downloads, dead symlinks, autoremove | macOS |
| Docker | Stopped containers, dangling images, volumes, builds | Both |
| Cargo | Rust registry and git cache | Both |
| Go | Build cache, test cache, module cache, lint cache | Both |
| Node | pnpm, pnpm, yarn, bun caches | Both |
| BuildCache | Gradle, Maven, SBT artifacts | Both |
| SystemCache | Spotlight, Xcode DerivedData, CocoaPods, pip, ccache | Both |
| TempFiles | Age-based temporary file removal | Both |
| ProjectExec | Old compiled scripts in ~/projects |
Both |
| CompiledBinaries | Large stale binaries | Both |
| GitHistory | Large blobs bloating git repos | Both |
| Golangci-lint | golangci-lint cache directory | Both |
Each cleaner auto-detects whether its target tool is installed and available. Unavailable cleaners are silently skipped.
| Mode | Flag | What Runs |
|---|---|---|
| Quick | --mode quick |
Homebrew, Go, Node, TempFiles, BuildCache |
| Standard | --mode standard |
All available cleaners |
| Aggressive | --mode aggressive |
Everything including system caches and full Docker volumes |
- Dry-run mode —
--dry-runpreviews every action without touching the filesystem - Confirmation dialogs — explicit yes/no before any deletion
- Protected generations — current Nix generation is never deleted
- Availability detection — only shows cleaners for installed tools
- Error classification — transient failures auto-retry; unavailable tools are skipped, not crashed
Built with a type-safe, extensible architecture:
- Type-safe enums — 27 cache types as compile-time constants, not strings
- Registry pattern — thread-safe cleaner registry with runtime registration
- Dependency injection —
samber/do v2container with typed accessors - Workflow engine —
Azure/go-workflowDAG with parallel execution and retry support - Functional error handling —
Result[T]type, no unchecked panics - Error classification —
go-error-familydrives retry decisions, skip/failed classification, and BSD sysexits exit codes - 300+ tests — unit, integration, BDD (Ginkgo), benchmarks, fuzz
clean-wizard/
├── cmd/clean-wizard/ # CLI entry point (Cobra)
├── internal/
│ ├── cleaner/ # 13 cleaner implementations + registry
│ ├── di/ # Dependency injection (samber/do v2)
│ ├── execution/ # Workflow orchestration (Azure/go-workflow)
│ ├── domain/ # Type-safe enums, settings, interfaces
│ ├── config/ # YAML configuration loading (Koanf)
│ ├── adapters/ # External tool adapters (Nix, Exec, HTTP)
│ ├── result/ # Result[T] functional error handling
│ └── format/ # Byte formatting, JSON output
├── tests/bdd/ # Ginkgo BDD tests
└── docs/ # Architecture documentation
clean-wizard clean [flags]| Flag | Description | Default |
|---|---|---|
--mode, -m |
Preset: quick, standard, aggressive |
standard |
--config, -c |
Path to config file | ~/.config/clean-wizard/config.yaml |
--profile, -p |
Configuration profile | "" |
--dry-run |
Preview without making changes | false |
--json |
Machine-readable JSON output | false |
--verbose |
Detailed logging | false |
--yes, -y |
Skip confirmation prompts | false |
--retries |
Retry attempts per cleaner (0=disabled) | 3 |
--retry-profile |
Preset: default, aggressive, conservative, none |
"" |
--concurrency, -C |
Max concurrent cleaners (0=unlimited) | 0 |
Scans and reports reclaimable space without cleaning:
clean-wizard scan # Scan all available cleaners
clean-wizard scan --json # JSON output
clean-wizard scan --verbose # Detailed breakdown# ~/.config/clean-wizard/config.yaml
presets:
quick:
cleaners: [homebrew, go, node, tempfiles, buildcache]
standard:
cleaners: [homebrew, go, node, cargo, tempfiles, buildcache, systemcache, docker, nix]
aggressive:
cleaners: [all]
include_dangerous: true
nix:
keep_generations: 5
docker:
timeout: 2m
include_volumes: true
tempfiles:
older_than: 7d
exclude_paths:
- /tmp/important-*# All tests
GOEXPERIMENT=jsonv2 go test ./... -short
# With race detector
GOEXPERIMENT=jsonv2 go test -race ./...
# BDD scenarios
GOEXPERIMENT=jsonv2 go test ./tests/bdd/...
# Coverage report
GOEXPERIMENT=jsonv2 go test -cover ./...Or use nix develop which sets GOEXPERIMENT=jsonv2 automatically.
# Build
GOEXPERIMENT=jsonv2 go build -o clean-wizard ./cmd/clean-wizard/
# Lint
golangci-lint run ./...
# Cross-compile
GOOS=darwin GOARCH=arm64 go build -o clean-wizard-darwin ./cmd/clean-wizard/Requires GOEXPERIMENT=jsonv2 (set automatically in the Nix devShell via nix develop).
Clean Wizard is the successor to SystemNix (a POSIX shell script):
| SystemNix | Clean Wizard | |
|---|---|---|
| Language | Shell | Type-safe Go |
| Dry-run | No | Yes |
| Interactive TUI | No | Yes |
| JSON output | No | Yes |
| Test coverage | Manual | 300+ tests |
| Configuration | Hardcoded | YAML profiles |
| Error handling | Exit codes | Classified errors with retry |
Full documentation lives at cleanwizard.lars.software.
- Fork and clone the repository
- Create a feature branch (
git switch -c feature/new-cleaner) - Run tests (
go test -race ./...) - Ensure linting passes (
golangci-lint run ./...) - Open a pull request
See the contributing guide for details.
- Website & Docs: cleanwizard.lars.software
- GitHub: github.com/LarsArtmann/clean-wizard
- Issue Tracker: github.com/LarsArtmann/clean-wizard/issues
- Predecessor: SystemNix
- Origin: Setup-Mac #111
MIT License. See LICENSE.