🧹 cleandev

Next-gen disk cleanup tool for developers. Reclaim tens of GBs by intelligently detecting and cleaning unnecessary development artifacts.

Goes beyond npkill — detects node_modules, .next, .expo, .gradle, DerivedData, dist, build and more. Smart recommendations based on last-modified time. Monorepo-aware. Safe by default.

Install

npm install -g cleandev

Or run without installing:

npx cleandev

Quick Start

# Scan your entire home directory — find and clean dev artifacts anywhere
cleandev

# Scan a specific path
cleandev --path ~/projects

# Scan only (dry run — nothing deleted)
cleandev scan

# Auto-delete safe folders (unused 30+ days)
cleandev clean --auto

# Force mode — even protected folders become selectable
cleandev --force

Commands

cleandev (default — interactive)

Scans the current directory, shows results, and lets you select folders to delete.

cleandev                    # Interactive cleanup in current directory
cleandev --path ~/projects  # Scan a different path

cleandev scan (dry run)

Only shows what's found — never deletes anything.

cleandev scan                         # Scan home directory
cleandev scan --path ~/projects       # Scan a specific path
cleandev scan --json                  # JSON output (pipe to jq, scripts, etc.)
cleandev scan --min-size 1048576      # Only show folders > 1 MB
cleandev scan --types node_modules,.next  # Only scan specific types
cleandev scan --force                 # Show protected folders as selectable

cleandev clean (with options)

cleandev clean --auto             # Auto-delete safe items (no prompt)
cleandev clean --auto --dry-run   # Show what auto-delete would remove
cleandev clean --safe-days 14     # Items unused 14+ days = safe
cleandev clean --force            # Even protected folders become selectable

Options

| Flag | Description | Default | |------|-------------|---------| | -p, --path <path> | Root path to scan | ~/ (home dir) | | -d, --depth <number> | Max directory depth | 10 | | -a, --auto | Auto-delete safe folders | false | | -t, --types <types> | Comma-separated folder types | all | | -i, --ignore <patterns> | Comma-separated ignore patterns | — | | --min-size <bytes> | Minimum folder size in bytes | 0 | | --safe-days <days> | Days unused before considered safe | 30 | | --sort <field> | Sort by: size, age, priority, type | size | | --json | Output as JSON | false | | --dry-run | Show what would be deleted | false | | --force | Allow deleting protected folders | false |

Supported Folder Types

| Type | Description | |------|-------------| | node_modules | Node.js dependencies | | .next | Next.js build cache | | .expo | Expo development cache | | DerivedData | Xcode derived data | | .gradle | Gradle build cache | | android/build | Android build output | | dist | Distribution build output | | build | Build output | | .turbo | Turborepo cache | | .svelte-kit | SvelteKit build cache | | .nuxt | Nuxt build cache | | .cache | Generic cache | | .parcel-cache | Parcel bundler cache | | coverage | Test coverage reports | | .output | Framework output |

Smart Recommendations

cleandev analyzes each folder and recommends:

• ✅ SAFE — Not modified in 30+ days. Pre-selected for deletion.
• ⚠️ REVIEW — Modified recently. Shown but not pre-selected.
• 🚫 PROTECTED — Critical path (monorepo root, current project). Never deleted.

Monorepo Support

cleandev automatically detects:

• npm/yarn workspaces
• pnpm workspaces
• Turborepo projects
• Lerna monorepos

Shared root-level node_modules in monorepos are protected from deletion.

Config File

Create cleandev.config.js in your project root:

export default {
  depth: 8,
  safeDays: 14,
  ignore: ['**/fixtures/**'],
  types: ['node_modules', '.next', 'dist'],
  minSize: 1048576, // 1 MB minimum
};

CLI flags override config file values.

Example Output

  🧹 cleandev — reclaim your disk space
  ══════════════════════════════════════════

  Found 8 cleanable folders
  Total size: 4.2 GB

  ✅ SAFE TO DELETE (3 items)
  These haven't been used recently.

  ○ 📦 node_modules (2.3 GB) — 45 days ago → SAFE
      projects/old-app/node_modules
  ○ ▲ .next (800 MB) — 2 months ago → SAFE
      projects/old-next/.next
  ○ 📱 .expo (450 MB) — 60 days ago → SAFE
      projects/expo-test/.expo

  ⚠️  REVIEW (2 items)
  These were used recently — double-check.

  ○ 📦 node_modules (320 MB) — 5 days ago → REVIEW
      projects/active-app/node_modules
  ○ 🔨 build (180 MB) — 12 days ago → REVIEW
      projects/active-app/build

  💡 You could free up 3.5 GB by deleting safe items.

Programmatic API

import { scan, enrichResults, cleanAll } from 'cleandev';

// Scan
const results = await scan({ path: '/projects', depth: 5 });

// Analyze
const enriched = enrichResults(results, { safeDays: 30 });

// Clean
const { totalFreed } = await cleanAll(enriched.filter(r => r.analysis.recommendation === 'safe'));
console.log(`Freed ${totalFreed} bytes`);

Safety

• Never deletes system directories
• Protects monorepo shared dependencies
• Protects current project's node_modules
• Always confirms before deleting (unless --auto)
• Handles permission errors gracefully

License

MIT