🧹 CleanStack

Reclaim disk space by cleaning development artifacts

A powerful, interactive CLI tool that helps developers reclaim disk space by identifying and safely removing common development artifacts like node_modules, build outputs, caches, Docker volumes, and more.

Features • Installation • Usage • Documentation • Contributing

✨ Features

• 🎯 Smart Detection - Automatically finds 20+ common dev artifacts across multiple languages and tools
• 📊 Visual Interface - Beautiful, interactive TUI for easy directory selection
• 🐳 Docker Support - Detects and cleans Docker volumes from docker-compose files
• 📏 Flexible Filtering - Filter by size, depth, custom patterns, or exclude specific directories
• 🛡️ Safety First - Multiple validation layers to prevent accidental deletions
• ⚡ Fast Scanning - Parallel processing for quick results even on large projects
• 🎨 Color Coded - Category-based color coding for easy identification
• 💾 Size Analysis - See exactly how much space each directory uses

🚀 Installation

npm (recommended)

npm install -g clean-stack-cli

npx (no installation)

npx clean-stack-cli scan

Requirements

• Node.js 18.0.0 or higher

📖 Usage

Quick Start

# Scan current directory
clean-stack-cli scan

# Scan specific directory
clean-stack-cli scan ~/projects

# Scan with size filter
clean-stack-cli scan --min-size 100MB

# Include Docker volumes
clean-stack-cli scan --docker-volumes

Interactive Controls

Once scanning completes, use these keyboard shortcuts:

| Key | Action | |-----|--------| | ↑ ↓ | Navigate through list | | Space | Toggle selection | | A | Select all | | D | Deselect all | | Enter | Confirm and delete | | Q / Esc | Quit without deleting |

Command Options

clean-stack-cli scan [path] [options]

Scan a directory for cleanable artifacts.

Options:

• --min-size <size> - Filter out directories smaller than specified size (e.g., 100MB, 1GB)
• --max-depth <depth> - Maximum directory depth to scan (default: 10)
• --include <patterns...> - Custom patterns to include (e.g., "build" "dist" "*.tmp")
• --ignore <patterns...> - Patterns to ignore (e.g., "important-cache" "keep-this")
• --docker-volumes - Include Docker volumes from docker-compose files

Examples:

# Clean up large artifacts
clean-stack-cli scan ~/projects --min-size 500MB

# Custom patterns only
clean-stack-cli scan --include "tmp" "*.backup" "old-*"

# Exclude specific directories
clean-stack-cli scan --ignore "node_modules" "important-dist"

# Docker projects
clean-stack-cli scan ~/docker-projects --docker-volumes

# Combine filters
clean-stack-cli scan --docker-volumes --min-size 1GB --max-depth 5

clean-stack-cli list

List all built-in patterns that will be scanned.

clean-stack-cli list

🗂️ What Gets Detected

Dependencies

• node_modules - npm/yarn/pnpm dependencies
• .pnpm - pnpm store
• bower_components - Bower dependencies
• venv, .venv, env, virtualenv - Python virtual environments

Build Outputs

• dist, build, out - Distribution and build directories
• .next - Next.js build output
• .nuxt - Nuxt.js build output
• target - Rust/Maven build output

Caches

• .cache - Generic cache directories
• .parcel-cache - Parcel bundler cache
• .turbo - Turborepo cache
• .pytest_cache, __pycache__ - Python caches
• .eslintcache - ESLint cache

Coverage Reports

• coverage - Code coverage reports
• .nyc_output - NYC coverage output
• htmlcov - Python coverage HTML reports

Infrastructure

• .terraform - Terraform cache

Docker Volumes

When using --docker-volumes flag:

• Local bind mounts from docker-compose files
• Relative volume paths (e.g., ./data, ./logs)
• Only volumes within the scanned directory

🛡️ Safety Features

CleanStack includes multiple safety mechanisms:

1. Path Validation - Only deletes within the scanned directory
2. System Directory Protection - Prevents deletion of system paths
3. Explicit Confirmation - Requires user selection and confirmation
4. No Symlink Following - Doesn't follow symbolic links during deletion
5. Error Handling - Gracefully handles permission errors and continues
6. Docker Volume Safety - Only includes existing local bind mounts

📚 Documentation

• Docker Volume Scanning - Comprehensive guide for Docker volume detection
• Examples - Real-world usage examples and patterns
• Contributing - Guide for contributors
• Changelog - Version history and updates

🔧 Development

Setup

git clone https://github.com/huantt/clean-stack-cli.git
cd cleanstack
npm install
npm link

Project Structure

cleanstack/
├── src/
│   ├── scanner/       # Directory scanning and pattern detection
│   ├── ui/            # Interactive terminal UI
│   ├── cleaner/       # Deletion logic
│   └── utils/         # Utility functions
├── bin/               # Executable entry point
└── tests/             # Test files

Running Tests

npm test

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

Areas for Contribution

• 🧪 Testing - Help add automated tests
• 📝 Documentation - Improve guides and examples
• 🎨 UI/UX - Enhance the interactive experience
• 🔍 Patterns - Add support for more artifact types
• 🌍 Localization - Add multi-language support

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with Commander.js for CLI framework
• Powered by Ink for beautiful terminal UIs
• Uses fast-glob for efficient file scanning

📊 Statistics

• 20+ patterns detected out of the box
• 5 categories (dependencies, build, cache, coverage, infrastructure)
• Docker support for containerized projects
• Zero config needed to get started

🌟 Star History

If you find CleanStack useful, please consider giving it a star on GitHub!

Made with ❤️ by developers, for developers

Report Bug • Request Feature • Documentation