devclean

devclean is a safety-first Rust CLI and native SwiftUI macOS menu bar app for auditing and removing rebuildable development artifacts. It reclaims Rust targets, JavaScript dependencies, framework/build/test caches, selected global caches, and unused Docker data while protecting tracked source, backups, databases, symlinks, mounts, and Docker volumes.

Safety by construction

Scan read-only and classify candidates using filesystem evidence.
Block candidates containing Git-tracked files by default.
Show an exact, size-sorted cleanup plan.
Require confirmation unless --yes is explicit.
Revalidate containment, category, type, and Git state immediately before deletion.
Atomically rename each candidate into a same-filesystem quarantine before recursive removal.
Never pass --volumes to Docker cleanup.

Quick start

# Audit generated artifacts older than one week and at least 500 MiB
devclean scan --all --older-than 7d --min-size 500MiB

# Save a privacy-safe HTML audit
devclean scan --all --global-caches --docker \
  --redact-paths --format html --output devclean-audit.html

# Conservative cleanup: target, node_modules, framework caches
devclean clean --select --report devclean-before.html

# Reclaim only enough to reach 100 GiB free
devclean clean --all --target-free 100GiB --yes

# Build cache only; volumes are untouched
devclean clean --docker --docker-older-than 168h --yes

# Broader Docker cleanup requires a distinct flag; still never volumes
devclean clean --docker-system --docker-older-than 168h --yes

Run devclean doctor to inspect roots, config search paths, tools, and active safety guarantees.

What it cleans

Category	Default clean	Opt-in	Evidence
Cargo `target`	Yes	—	Exact name plus Cargo build markers
`node_modules`	Yes	—	Exact dependency-directory name
Framework cache	Yes	—	Known names such as `.next` and `.svelte-kit`
Build/test output	No	`--all`	Recognized manifest plus exact generated name
Package/tool cache	No	`--global-caches`	Exact platform-aware allowlist
Model/runtime cache	No	`--expensive-caches`	Separate allowlist because redownload cost is high
Docker build cache	No	`--docker`	`docker builder prune`, never volumes
Docker system data	No	`--docker-system`	Stopped containers, unused images/networks/cache; never volumes

Ambiguous dist, out, coverage, archives, user data, database paths, VCS metadata, and Docker volumes remain out of scope.

Filters and selection

--older-than 30d: require the newest observed file to be old enough.
--min-size 1GiB: ignore small candidates.
--exclude 'vendor/**': skip matching absolute, root-relative, or basename paths.
--select: choose candidate numbers and ranges interactively.
--only-path PATH: clean exact paths emitted by a previous JSON scan; every path must pass a fresh scan or the operation aborts.
--target-free 100GiB: select only enough largest candidates to reach a free-space target on the first root filesystem.
--allow-tracked: explicit escape hatch for vendored/generated content committed to Git.

Configuration

devclean loads the first existing file from ./devclean.toml or the platform config directory. Pass --config PATH to select one explicitly. CLI values override config values.

[scan]
roots = ["/Users/me/Dev"]
exclude = ["vendor/**", "archive/**"]
older_than = "14d"
min_size = "100MiB"
max_depth = 24

[clean]
protect_git_tracked = true
expensive_caches = false

See devclean.example.toml.

Reports and automation

devclean scan --format table
devclean scan --format json --redact-paths
devclean scan --format jsonl --redact-paths
devclean scan --format html --output report.html --redact-paths

HTML and JSON can contain private absolute paths unless --redact-paths is used. JSONL emits one candidate event per line followed by a summary event.

Generate shell integrations without extra packages:

devclean completions zsh > _devclean
devclean completions bash > devclean.bash
devclean manpage --output devclean.1

Installation

GitHub release

Download the archive for your platform from the latest release, verify SHA256SUMS, then verify build provenance:

gh attestation verify devclean-*.tar.gz -R tuanle96/devclean

Cargo

The crates.io package is named devclean-cli; the installed executable is devclean.

cargo install devclean-cli --locked

Homebrew

brew install tuanle96/tap/devclean

Native macOS menu bar app

The SwiftUI app displays free space, previews reclaimable artifacts, supports exact per-candidate selection, and asks for destructive confirmation. It bundles the same Rust helper used by the CLI and never deletes files from Swift.

apps/macos/scripts/build-app.sh
open dist/Devclean.app

Local source builds are ad-hoc signed unless CODE_SIGN_IDENTITY is provided. Published menu bar archives are Developer ID signed, notarized by Apple, stapled, and Gatekeeper-verified. See apps/macos.

Build from source

git clone https://github.com/tuanle96/devclean.git
cd devclean
cargo install --path . --locked

The minimum supported Rust version is 1.85.

Codex skill

The companion skill lives at skills/dev-disk-cleaner:

cp -R skills/dev-disk-cleaner ~/.codex/skills/dev-disk-cleaner

It standardizes audit, authorization, narrow cleanup, HTML evidence, regeneration diagnosis, and post-clean verification.

Development

cargo fmt --all -- --check
cargo test --all-features --locked
cargo clippy --all-targets --all-features --locked -- -D warnings
cargo package --locked
swift test --package-path apps/macos
apps/macos/scripts/build-app.sh

See architecture, safety model, performance, distribution, and contributing.

Community and security

Ask usage questions in GitHub Discussions.
Report bugs through GitHub Issues.
Report vulnerabilities privately according to SECURITY.md.
Participation is governed by CODE_OF_CONDUCT.md.

License

Released under the MIT License.

devclean-cli 0.3.1