reclaimit — Developer disk cleanup CLI

reclaimit is a cross-platform Go CLI and terminal UI for developer disk cleanup. It finds regenerable build artifacts and caches, groups them by project, and lets you review them before deletion.

Traditional disk analyzers answer “what is large?”. reclaimit adds the developer context needed to answer “what can I recreate if I delete it?”.

The demo uses generated files and makes no typical-savings claim. Its exact fixture and commands are documented in docs/demo.md.

Install

Install the latest published release from the GitHub Releases page, or use Homebrew when available. For a source install, use Go 1.25.12 or newer:

go install github.com/svg153/reclaimit/cmd/reclaimit@v0.9.0

Release archives include SHA-256 checksums; the installer verifies the checksum before writing a destination file. Run reclaimit doctor after installing to check the local binary, runtime, and shell environment without scanning or modifying files.

What it does

• Detects 17 cleanup categories for JavaScript, Python, Rust, frontend builds, Bun, pip, pipx, and macOS metadata.
• Groups candidates by Git repository or path depth instead of presenting one flat list.
• Produces plain-text, Markdown, or JSON reports with per-candidate safety notes, plus an interactive TUI.
• Requires explicit confirmation for cleanup and supports a non-destructive --dry-run.
• Revalidates identity, type, size, and modification snapshot, then uses a same-filesystem quarantine so changed data is preserved.
• Exports and imports versioned JSON selection manifests for repeatable, auditable dry runs; changed or missing candidates fail closed and are reported.
• Ships as one Go binary for Linux, macOS, and Windows.

Quick start

# Inspect a workspace in the terminal
reclaimit analyze --root "$HOME/code"

# Check the local installation before scanning
reclaimit doctor

# Export machine-readable scan metrics
reclaimit analyze --root "$HOME/code" --format json --out reclaimit-report.json

# Share aggregate results without exposing local paths
reclaimit analyze --root "$HOME/code" --format json --anonymous

# Compare two versioned reports without rescanning the filesystem
reclaimit diff before.json after.json

# Review candidates interactively
reclaimit tui --root "$HOME/code"

# Preview one category without deleting anything
reclaimit clean --root "$HOME/code" --include-category python-venv --dry-run

# Save a reviewed selection, then validate it later
reclaimit analyze --root "$HOME/code" --older-than 30d --export-selection selection.json
reclaimit clean --root "$HOME/code" --import-selection selection.json --dry-run

# Create an explicit cleanup plan, review it, then dry-run or apply it
reclaimit analyze --root "$HOME/code" --export-plan cleanup-plan.json
reclaimit clean --root "$HOME/code" --plan cleanup-plan.json --dry-run
reclaimit clean --root "$HOME/code" --plan cleanup-plan.json --yes

# Delete only after reviewing the same selection
reclaimit clean --root "$HOME/code" --include-category python-venv --yes

Supported cleanup categories

Ecosystem	Detected paths
JavaScript and frontend	node_modules, dist, build, .next, .nuxt
Python	.venv, venv, __pycache__, *.pyc, *.pyo, .pytest_cache, .mypy_cache, .tox
Python package tools	.cache/pip, .local/pipx
Rust	target
Bun	.bun/install/cache
Generic caches	.cache
macOS	.DS_Store, .Spotlight-V100, .Trashes

Generic caches and pipx-managed environments can contain useful or costly-to-recreate data. reclaimit describes these candidates but leaves the decision to you.

reclaimit vs ncdu, gdu, dust, and dua

ncdu, gdu, dust, and dua are general disk usage analyzers. reclaimit is narrower: it recognizes developer artifacts and adds a guarded, project-aware cleanup workflow. It is a companion for these tools, not a drop-in replacement.

Capability	reclaimit	General disk analyzer
Primary signal	Regenerable artifact category	File and directory size
Project context	Git repository or path grouping	Filesystem hierarchy
Automation output	JSON, Markdown, plain text	Tool-dependent
Cleanup guard	Dry run plus pre-delete revalidation	Tool-dependent/manual selection

The tools complement each other: use a general analyzer to understand the whole disk and reclaimit to review known developer cleanup candidates.

Commands and important flags

Command	Purpose
analyze	Scan and produce a report
tui	Review results in an interactive terminal tree
clean	Preview or delete selected candidates
doctor	Check the local installation and runtime environment

• --root PATH: directory to scan; defaults to the current directory.
• --format plain|markdown|json: report format. JSON candidates include description and safety_note fields for automation.
• --group-mode repo|depth: group by Git repository or path depth.
• --max-depth N: traversal limit; 0 means unlimited.
• --workers N: global scanner concurrency ceiling; defaults to 8.
• --include-category VALUE: include one category; repeatable.
• --exclude-category VALUE: exclude one category; repeatable.
• --exclude-group PATH: exclude a path prefix; repeatable.
• --exclude-path PATH: exclude one exact candidate path; repeatable.
• --ignore-file FILE: read excluded paths from a file, one per line.
• --older-than DURATION: keep only candidates older than a duration such as 30d.
• --risk-profile conservative|balanced|expanded: choose how broad candidate detection should be. balanced is the default and preserves the standard category set; conservative keeps only low-risk regenerable artifacts.
• --export-selection FILE: write a versioned JSON manifest of the reviewed selection.
• --import-selection FILE: validate a manifest; it never bypasses --dry-run or --yes.
• --export-plan FILE: write an explicit, owner-only cleanup plan containing the reviewed candidates and their identity snapshot.
• --plan FILE: validate a cleanup plan before clean; any root, traversal, category, type, size, or modification mismatch stops the operation.
• --out FILE: write the report to a file.
• --dry-run: run cleanup preflight without deleting.
• --yes: confirm destructive cleanup.
• --anonymous: redact root, path, group, mismatch, and cleanup recovery paths in generated reports.
• --inactive-projects DURATION: report projects with old relevant activity and regenerable artifacts as review-only findings.

reclaimit diff BEFORE.json AFTER.json compares selected bytes, category totals, and candidate drift between two versioned JSON reports. Anonymous reports keep aggregate comparisons, while path-level candidate changes are intentionally omitted. JSON reports include schema_version; diff rejects missing or newer schemas instead of guessing how to interpret them.

--inactive-projects is deliberately opt-in. It requires a recognized project marker, old relevant marker or source activity, and at least one generated artifact. Findings are reported separately with review_only: true; they are never cleanup candidates and never enter selection manifests.

Run reclaimit help analyze, reclaimit help tui, reclaimit help clean, or reclaimit help doctor for the complete help text.

Safety model

analyze and tui are read-only. clean requires either --dry-run or --yes.

Each reported cleanup candidate includes a safety note that explains why the matched artifact is reviewable, for example because it is a cache, build output, or dependency directory that can be regenerated. Candidates also carry a risk_level; use --risk-profile conservative to exclude categories that need broader manual review.

Use --anonymous when sharing a report publicly. It preserves aggregate sizes, category counts, risk levels, and safety notes, while replacing local roots, groups, candidate paths, mismatch paths, and cleanup recovery paths with <redacted>. Cleanup previews and TUI reproduction commands are also redacted. Selection manifests remain operational and contain real paths, so do not share them publicly.

Cleanup plans are also operational files and contain real paths. A plan is never applied implicitly: clean --plan FILE still requires --dry-run or --yes, and any mismatch stops the entire plan before deletion begins. Review the plan and its dry-run output before using --yes.

Before deleting, reclaimit collapses nested selections and checks that each path still exists and matches the type, identity, size, and modification snapshot observed by the scan. It then atomically renames each verified item into a private same-filesystem quarantine, checks it again, and only deletes the quarantined object. Changed data is preserved and its recovery path is included in plain-text, Markdown, and JSON cleanup results.

Deletion is still irreversible and cannot be transactional on a normal filesystem. Review the dry run, keep backups for valuable data, and avoid running cleanup against paths you do not understand.

Build and contribute

git clone https://github.com/svg153/reclaimit.git
cd reclaimit

go test ./...
go test -race ./...
go vet ./...
go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.1.6 run ./...
go build -o ./bin/reclaimit ./cmd/reclaimit

The optional Task shortcuts are documented in Taskfile.yml. See CONTRIBUTING.md for contribution guidelines and docs/architecture.md for the design, scanner limits, and cleanup contract.

Performance measurements include their fixture, environment, raw command, and interpretation limits in docs/benchmarks.md. Growth is tracked without product telemetry in docs/growth.md.

Roadmap

• Expand cleanup categories only with explicit safety descriptions and tests.
• Keep behavioral coverage above 90% overall and in every production package and source file.
• Expand the documented selection-manifest workflow and add new safe categories with tests.
• Review release acquisition after 30 days and select new cleanup categories from opt-in, privacy-preserving evidence.

Focused pull requests, bug reports, category proposals, and documentation improvements are welcome.

License

MIT — see LICENSE.