🔪 modkill

📸 Demo

$ modkill --path ~/Projects --depth 4

✔ Scan complete: 42 candidate(s)

Project (relative path below)                     Size         Age
◉ old-project                                   1.98 GB       482d
  old-project/frontend
◉ abandoned-poc                                  856 MB       127d
  experiments/abandoned-poc
◯ active-project                                 328 MB         3d
  work/active-project

Total to free: 2.8 GB
? Proceed to delete 2 folders? (y/N)

🎯 Why modkill?

Every developer's disk is littered with forgotten node_modules folders:

• Gigabytes wasted: Each project can have 100MB-2GB of dependencies
• Accumulation: Old projects, experiments, tutorials pile up over months
• Hidden bloat: Nested in various directories, hard to find manually

modkill solves this with:

• ⚡ Fast parallel scanning using optimized filesystem traversal
• 🧠 Smart detection of abandoned projects by age and size
• 🛡️ Safe by default with dry-run, trash, and restore logs
• 🎨 Beautiful UX with interactive selection and progress indicators
• 🔧 Flexible with JSON output for automation

📦 Installation

# Quick one-time use
npx @lisandrof/modkill

# Global install
npm install -g @lisandrof/modkill

# Using Yarn
yarn global add @lisandrof/modkill

# Using pnpm
pnpm add -g @lisandrof/modkill

Requirements

• Node.js 18.0.0 or higher
• macOS, Linux, or Windows
• 50MB free RAM

🚀 Quick Start

# Interactive mode - select what to delete
modkill

# Scan your entire home directory
modkill --path ~ --depth 4

# Auto-clean old modules (>30 days)
modkill --auto

# Preview without deleting anything
modkill --dry-run

# Clean current project only
modkill --current

📖 Commands & Options

Basic Commands

| Command | Description | | ------------------- | ------------------------------------------ | | modkill | Interactive mode with checkbox selection | | modkill --auto | Automatically clean old modules (>30 days) | | modkill --dry-run | Preview what would be deleted | | modkill --current | Clean only current directory |

Options

| Option | Type | Default | Description | | ------------------ | ------- | ------- | ----------------------------------------- | | --path <dir> | string | . | Root directory to scan | | --depth <n> | number | 6 | Max recursion depth | | --min-age <days> | number | 0 | Only show modules older than N days | | --min-size <mb> | number | 0 | Only show modules larger than N MB | | --sort <by> | string | size | One of: size, age, name, path | | --json | boolean | false | Output JSON for scripting | | --yes | boolean | false | Skip confirmation (interactive mode only) | | --help | boolean | false | Show help |

Advanced Examples

# Auto-clean with age and size filters
modkill --path ~/Projects --min-age 60 --min-size 100

# Auto-clean with custom thresholds
modkill --auto --min-age 90 --min-size 200

# Generate JSON report for analysis
modkill --dry-run --json --path ~ > report.json

# Clean current directory (no confirmation by design)
modkill --current

# Auto-clean only large modules (>200MB)
modkill --min-size 200

# Focus on abandoned projects (oldest first, interactive)
modkill --path ~ --sort age

# Deep scan of an external drive
modkill --path /Volumes/Backup --depth 10

🎨 Interactive Mode Features

Smart Table Display

• Project name with color coding:
  • 🔴 Red: >60 days old
  • 🟡 Yellow: 30-60 days old
  • 🟢 Green: <30 days old
• Size in human-readable format (KB, MB, GB)
• Age in days or months
• Path shown as subtitle (relative to scan root)

Selection Interface

• Space: Select/deselect item
• A: Toggle all
• I: Invert selection
• Enter: Proceed with deletion
• Ctrl+C: Cancel

Safety Features

• ✅ Interactive preview with confirmation prompt
• 🗑️ Moves to OS trash (recoverable)
• 📝 Creates restore log in system temp directory (modkill-restore-[timestamp].log)
• ⚠️ Dry-run mode available for risk-free preview
• 🚫 Skips system directories automatically

How it decides

• Filter: applies --min-age and --min-size when provided
• Sorting: default by size (use --sort age|name|path to override)
• Pre-selection (interactive): auto-selects items older than 30 days
• Scoring: weighted formula ageScore×0.5 + sizeScore×0.4 + orphanBonus×0.1
• Colors: 🟢 ≤30d, 🟡 31–60d, 🔴 >60d

📊 JSON Output Schema

[
  {
    "path": "/absolute/path/to/node_modules",
    "sizeBytes": 134217728,
    "mtimeMs": 1699564800000,
    "hasPackageJson": true,
    "ageDays": 45.5,
    "score": 67.3
  }
]

Fields:

• path: Absolute path to node_modules folder
• sizeBytes: Total size in bytes
• mtimeMs: Last modified timestamp (milliseconds)
• hasPackageJson: Whether parent has package.json
• ageDays: Days since last modification
• score: Heuristic priority score (weighted by age, size, and orphan status)

⚡ Performance

| Metric | Result | | ------------------- | -------- | | Scan home (277GB) | 52.7s | | Memory usage (peak) | <50MB | | Single project scan | 0.21s | | Parallel scanning | ✅ Ready |

Benchmarks

Tested on M-series Mac:

# Scan home directory (277GB, depth 6)
✓ Found 54 node_modules totaling 18GB in 52.7s

# Scan projects directory
✓ Found 11 node_modules totaling 4.7GB in 47.9s

# Scan current project
✓ Found 1 node_modules in 0.21s

🛠️ Development

Setup

# Clone repository
git clone https://github.com/udede/modkill.git
cd modkill

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Link for local testing
npm link

Scripts

| Script | Description | | ---------------- | ---------------------------- | | npm run dev | Watch mode with auto-rebuild | | npm run build | Build for production | | npm test | Run all tests | | npm run lint | Lint and fix code | | npm run format | Format with Prettier | | npm run bench | Run benchmarks |

Project Structure

modkill/
├── src/
│   ├── cli.ts              # CLI entry point
│   ├── core/               # Core logic
│   │   ├── scanner.ts      # Filesystem traversal
│   │   ├── analyzer.ts     # Filtering & scoring
│   │   └── cleaner.ts      # Safe deletion
│   ├── commands/           # Command handlers
│   └── ui/                 # UI components
├── tests/                  # Test suites
└── dist/                   # Built files

🧪 Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific suite
npm test scanner

# E2E tests
npm run test:e2e

🤝 Contributing

We love contributions! This project uses automated releases with changesets.

Quick Start

1. Fork the repository
2. Create your feature branch (git checkout -b feat/amazing-feature)
3. Make your changes
4. Add tests for new features
5. Create a changeset: npm run changeset
6. Commit your changes (including the changeset file)
7. Push and open a Pull Request

For detailed guidelines, see:

• 📖 Contributing Guide
• 🚀 Release Process
• ⚙️ Setup Guide (for maintainers)

Automated Releases

This project uses GitHub Actions for automated releases:

• ✅ CI runs on every PR
• ✅ Changesets bot creates release PRs automatically
• ✅ Packages publish to npm automatically when release PR is merged
• ✅ Changelog is auto-generated

No manual npm publish needed! 🎉

📝 Changelog

See CHANGELOG.md for version history.

🏆 Comparison

| Feature | modkill | npkill | node-prune | | --------------- | ------------------- | ------------ | ------------ | | Speed | ⚡⚡⚡⚡⚡ Parallel | ⚡⚡⚡ | ⚡⚡ | | Interactive UI | ✅ Rich & colorful | ✅ Basic | ❌ | | Safe deletion | ✅ Trash + log | ⚠️ Permanent | ⚠️ Permanent | | JSON output | ✅ | ❌ | ❌ | | Custom filters | ✅ Age, size | ⚠️ Limited | ❌ | | Monorepo aware | ✅ Depth control | ⚠️ | ❌ | | Windows support | ✅ | ✅ | ⚠️ |

🐛 Troubleshooting

Common Issues

Permission denied

# Run with sudo if scanning system directories
sudo modkill --path /usr/local

Slow scanning

# Reduce depth for faster scans
modkill --depth 3

# Auto-clean only large folders (>100MB) for faster cleanup
modkill --min-size 100

Not finding modules

# Increase depth
modkill --depth 10

# Check specific path
modkill --path ./my-project

📄 License

MIT © Francesco Lisandro