lib-cleaner

A CLI tool to clean up dependency directories from various package managers and reclaim disk space.

Features

• 🔍 Smart Detection: Automatically identifies projects by their marker files
• 🚀 Multi-Language Support: Node.js, Python, Rust, Maven, Gradle (with opt-in for Go, Ruby, PHP)
• 📊 Size Reporting: Shows how much space you'll reclaim (with optional fast mode)
• 🏃 Efficient Scanning: Skips known dependency directories for fast traversal
• 🛡️ Production-Safe: Multiple safety guards against accidental deletion
• ✨ Interactive: Confirmation prompt before deletion
• 🔒 Security: Protects against symlink traversal, system directories, and infinite loops
• ✅ Validated: Python venvs are verified before deletion to avoid false positives

Supported Project Types

| Type | Marker Files | Cleaned Directories | Notes | |------|--------------|---------------------|-------| | Node.js | package.json | node_modules | Always enabled | | Python | requirements.txt, pyproject.toml, Pipfile, setup.py | .venv, venv, .virtualenv | Validated as actual venvs | | Rust | Cargo.toml | target | Always enabled | | Maven | pom.xml | target | Always enabled | | Gradle | build.gradle, build.gradle.kts, settings.gradle | build | Always enabled | | Go | go.mod | vendor | Requires --include-vendor flag ⚠️ | | Ruby | Gemfile | vendor/bundle | Requires --include-vendor flag ⚠️ | | PHP | composer.json | vendor | Requires --include-vendor flag ⚠️ |

Note: Vendor directories often contain committed code and may not be regenerable. Use --include-vendor with caution.

Installation

Global Installation (Recommended)

npm install -g lib-cleaner

Local Installation

npm install lib-cleaner

Run with npx (No Installation)

npx lib-cleaner scan

Usage

Scan (Dry-run Mode)

Preview what will be deleted without actually removing anything:

lib-cleaner scan [path]

Options:

• path: Directory to scan (defaults to current directory)
• -d, --depth <number>: Maximum depth to scan (default: 10, max: 100)
• --include-vendor: Include vendor directories (Go, Ruby, PHP) - USE WITH CAUTION
• --skip-size: Skip size calculation for faster scanning

Examples:

# Scan current directory
lib-cleaner scan

# Scan specific directory with custom depth
lib-cleaner scan ~/projects --depth 5

# Include vendor directories (careful!)
lib-cleaner scan ~/projects --include-vendor

# Fast scan without size calculation
lib-cleaner scan ~/projects --skip-size

Clean

Remove dependency directories:

lib-cleaner clean [path]

Options:

• path: Directory to clean (defaults to current directory)
• -d, --depth <number>: Maximum depth to scan (default: 10, max: 100)
• -y, --yes: Skip confirmation prompt
• --include-vendor: Include vendor directories (Go, Ruby, PHP) - USE WITH CAUTION
• --skip-size: Skip size calculation for faster scanning

Examples:

# Interactive mode (will ask for confirmation)
lib-cleaner clean ~/projects

# Auto-confirm mode
lib-cleaner clean ~/projects --yes

# Limit scan depth
lib-cleaner clean ~/projects --depth 3

# Include vendor directories with confirmation
lib-cleaner clean ~/projects --include-vendor

# Fast clean without size calculation
lib-cleaner clean ~/projects --skip-size --yes

Example Output

🔍 Scanning for dependency directories...

Found 3 dependency directories:

1. NODE project
   Path: /Users/you/projects/my-app
   Deps: /Users/you/projects/my-app/node_modules
   Size: 234.56 MB

2. PYTHON project
   Path: /Users/you/projects/ml-project
   Deps: /Users/you/projects/ml-project/.venv
   Size: 1.23 GB

3. RUST project
   Path: /Users/you/projects/rust-app
   Deps: /Users/you/projects/rust-app/target
   Size: 456.78 MB

Total size to reclaim: 1.92 GB

Run 'lib-cleaner clean' to remove these directories.

Safety Features

This tool has multiple layers of protection against accidental data loss:

1. System Directory Protection

• Refuses to operate on root (/) or system directories (/usr, /bin, /etc, etc.)
• Blocks Windows drive roots (C:\, D:\, etc.)
• Validates all input paths before proceeding

2. Symlink Safety

• Uses lstat instead of stat to avoid following symlinks
• Skips symlinked directories entirely
• Prevents directory traversal attacks and infinite loops

3. Input Validation

• Depth must be a valid number between 0 and 100
• All paths are validated before scanning
• Clear error messages for invalid input

4. Python Virtualenv Verification

• Validates that directories are actually virtual environments
• Checks for pyvenv.cfg, bin/activate, or Scripts/activate
• Prevents deletion of non-venv folders named .venv or venv

5. Vendor Directory Protection

• Vendor directories (Go, Ruby, PHP) are opt-in only
• Requires explicit --include-vendor flag
• Shows warning about potential committed code

6. Pre-Deletion Validation

• Re-verifies paths before deletion
• Confirms paths are still directories (not symlinks)
• Tracks actual reclaimed size (not estimates)
• Reports failed deletions separately

7. Concurrency Limiting

• Limits concurrent filesystem operations to prevent system overload
• Prevents EMFILE (too many open files) errors
• Stable performance on large directories (e.g., huge node_modules)

8. Deduplication

• Prevents adding the same directory multiple times
• Handles projects with multiple package managers

How It Works

1. Project Detection: Scans directories for marker files (e.g., package.json, requirements.txt)
2. Dependency Identification: Checks if corresponding dependency directories exist and validates them
3. Size Calculation: Calculates total size of each dependency directory (optional with --skip-size)
4. Safe Deletion: Removes only validated dependency directories, never source code

Smart Scanning

The tool is optimized for efficiency and safety:

• ✅ Only recurses into potential project directories
• ✅ Skips known dependency directories (won't scan inside node_modules)
• ✅ Skips system directories and hidden folders
• ✅ Never follows symlinks
• ✅ Handles permission errors gracefully
• ✅ Limits concurrent operations to prevent system overload

Reinstalling Dependencies

After cleaning, you can reinstall dependencies anytime:

# Node.js
npm install

# Python
pip install -r requirements.txt
# or
poetry install

# Maven
mvn compile
# or
mvn package

# Gradle
gradle build
# or
./gradlew build

# Go
go mod download

# Rust
cargo build

License

MIT