🧹 cruft-cleaner

An interactive terminal tool that finds Python virtual environments, node_modules, build artifacts, and other heavy dev-environment directories across your file system — then lets you select which ones to delete with a simple checkbox UI.

Zero external dependencies — uses only Python's standard library (curses). Works on macOS and Linux.

🚀 Quick Start

# One-time use (no installation needed)
npx cruft-cleaner

# Install globally
npm install -g cruft-cleaner
cruft

# Scan a specific directory
cruft --path ~/projects

# Dry run — just list what would be deleted, no changes
cruft --dry-run

# Limit search depth (default is 10 levels deep)
cruft --depth 5

🎮 TUI Controls

| Key | Action | |-----|--------| | ↑ / k | Move cursor up | | ↓ / j | Move cursor down | | Page Up/Down | Scroll a page | | Space | Toggle selection | | a | Select all | | d | Deselect all | | Enter | Confirm & delete selected | | q / Esc | Quit without deleting |

� What It Detects

| Category | Directory Names | |----------|----------------| | Python | venv, .venv, env, __pycache__, .mypy_cache, .pytest_cache, .tox, dist, build, *.egg-info, … | | Node / JS | node_modules, .npm, .yarn, .next, .nuxt, .turbo, .parcel-cache, … | | Rust | target/ (only when Cargo.toml exists next to it) | | Java / Gradle | .gradle, .m2 | | Ruby | .bundle | | General | .cache, .ruff_cache, .DS_Store |

🛡️ Safety

• Confirmation prompt — after pressing Enter in the TUI, a final Proceed? [y/N] prompt is shown before any files are removed
• --dry-run mode — prints the list without touching anything
• The script never descends into deleted directories, so double-counting is impossible

📋 Requirements

• Python 3.10+ (auto-detected)
• curses module (built into Python on macOS and Linux)

Windows users: The curses module is not included in standard CPython on Windows. Install windows-curses via pip: pip install windows-curses

🔄 Updates

The package automatically checks for updates every 24 hours. You can also check manually:

cruft --update

� Troubleshooting

Python not found:

# Ensure Python 3.10+ is installed
python3 --version

# On Windows, install windows-curses
pip install windows-curses

Permission denied:

# Make scripts executable
chmod +x bin/*.js

� License

MIT License - see LICENSE file for details.

🔗 Links

• Source Code: https://github.com/Chetan-Chinchulkar/cruft
• npm Package: https://www.npmjs.com/package/cruft-cleaner
• Issues: https://github.com/Chetan-Chinchulkar/cruft/issues

Made with ❤️ by Chetan Chinchulkar