Flagship — open source
devklean
A CLI tool that finds and safely removes build artifacts across your dev projects — zero data-loss guarantee via safe-delete, not permanent rm.
Overview
devklean is a Python CLI that reclaims disk space by finding and safely removing regenerable development artifacts — node_modules, .venv, build caches — across your projects. It is published on PyPI, tested in CI, and maintained with community contributions.
Its defining constraint: zero data loss. Nothing is ever rm -rf'd — every deletion goes to the native system trash, so a mistake is recoverable.
Problem
Development trees quietly accumulate gigabytes of regenerable junk. The obvious fix — find | xargs rm -rf — is a loaded gun: one mistyped path or overeager glob deletes real work. Existing cleaners either don't know what's safe to remove or remove it irreversibly.
Solution
devklean scans a tree, shows exactly what it found and how big each item is, and only then deletes — to the Recycle Bin on Windows, Trash on macOS, freedesktop trash on Linux, via send2trash. Large deletions require an explicit typed confirmation, dangerous paths are refused outright, and every operation is recorded in a history you can review with devklean history.
The command surface is deliberately small: scan (never deletes), clean (scan + confirm + trash), restore (how to recover), history, and doctor (inspect and repair the metadata store). Running bare devklean defaults to clean; --json output makes it scriptable.
Architecture
A scanner walks the tree matching known artifact patterns and sizes them. A deletion layer wraps send2trash with the safety policy — path validation, typed confirmation thresholds, and a metadata store recording each operation (timestamp, size, strategy, item count). The CLI front-end presents scan results and drives confirmation flow.
Packaging targets Python 3.8+ (tomli backfills TOML parsing below 3.11), ships via PyPI, and recommends pipx for isolated installs. CI runs on GitHub Actions.
devklean clean ──► scanner walks the tree
│ matches artifact patterns
│ (node_modules · .venv · caches)
▼
scan report (paths + sizes)
│
▼
safety policy
path validation · typed confirmation
for large deletions
│ dangerous path │ confirmed
▼ ▼
refused send2trash ──► OS trash
│ (recoverable)
▼
metadata store ──► devklean historyTech stack
Challenges
- Trash semantics differ per platform — three different trash implementations behind one behavioral guarantee.
- Safety UX is a balance: enough friction that a 40 GB deletion is deliberate, little enough that daily use isn't annoying.
- Supporting Python 3.8 through current versions constrains dependencies and syntax more than expected.
Lessons learned
- Safety is a product feature, not a disclaimer — 'trash-backed, always recoverable' is the reason the tool is trustable enough to use casually.
- A small, predictable command surface (scan / clean / restore) is easier to trust than a flag forest.
- Publishing on PyPI with CI changed the discipline: version hygiene, changelogs, and backward compatibility became real constraints once strangers installed it.
Future improvements
- More artifact types and per-project configuration.
- Age-based policies — only clean artifacts untouched for N days.
- Scheduled cleans and size budgets.