Developer machines fill up quietly. node_modules, build caches, package manager stores, old tool data, and forgotten Docker layers add up to tens of gigabytes. smartclean is a small CLI that finds that cruft and removes it safely.
What it does
- Scans common locations for reclaimable space:
node_modules,.cache, build output, package manager caches. - Shows what it found with sizes before touching anything.
- Requires confirmation; supports
--dry-runto preview. - Never deletes a directory that is not safely reproducible; it skips anything it cannot verify.
Install
git clone https://github.com/farishan/smartclean.git ~/dev/smartclean
cd ~/dev/smartclean && bash install.sh
Requires: bash, coreutils, find, du, stat. Optional: mo (Mole / mole-for-ubuntu) for system-level helpers.
Usage
smartclean # full scan, no changes
smartclean scan --json # JSON report
smartclean scan --deep # include deep sweeps
smartclean scan --keep-days 14 # protect 14-day-old caches
smartclean scan --target ~/dev # artifacts/large files under ~/dev
smartclean apply --category artifacts --target ~/dev
smartclean apply --yes # apply all (confirms per category unless --yes)
The scan output groups by category so you can see where the space went. Most machines recover 5-20 GB on the first run.
Safety first
The default is conservative. smartclean will not remove a directory unless it can confirm it is regenerable (lockfile present, cache directory, known build output). If you are unsure, --dry-run shows exactly what would be deleted.
Why I built it
I kept running out of disk on a laptop with a 256 GB SSD. Existing tools either required a GUI or deleted too aggressively. smartclean is the middle ground: fast, terminal-native, and safe.
Links
- Repo: farishan/smartclean
- Releases: releases
Feedback welcome. If it deletes something it should not have, open an issue with the path and I will add a guard.
What I learned shipping it
The hardest part was not the scanning; it was deciding what counts as safe. A directory with a lockfile next to it is safe. A directory without one is not, even if it looks like a cache. When in doubt, smartclean skips and tells you why.
The first version is intentionally small: scan, preview, clean. Future releases will add per-directory allowlists and a JSON output mode for scripting.
Top comments (0)