I Built a CLI Tool to Reclaim Disk Space from node_modules — Here's How It Works

The Problem — node_modules Is a Disk Space Leak

A fresh npm install on a typical Node.js project pulls in anywhere from 50MB to 500MB of dependencies. That's fine for one project. But most developers have dozens of projects cloned on their machine — side projects, client work, open source contributions, tutorials they started and forgot about.

Those node_modules folders sit there indefinitely. You don't need them unless you're actively working on that project. But they're invisible — you don't see them in Finder or Explorer unless you go looking. Meanwhile they quietly consume gigabytes.

The manual approach is tedious: open each project folder, check if there's a node_modules, estimate the size, decide whether to delete it. Repeat for 40 projects. Nobody does this consistently.

So I built deepclean-cli — a single command that scans an entire directory tree, finds every matching folder, tells you exactly how much space each one is using, and removes them after a confirmation prompt.

Install and Run

Install it globally once and use the deepclean command anywhere:

npm install -g deepclean-cli

Or run it without installing via npx:

npx deepclean-cli -d ~/code

Point it at your projects folder and run a dry-run first to see what it finds:

deepclean -d ~/code --dry-run

Output looks like this:

Scanning "/Users/zain/code" up to 3 level(s) deep for "node_modules"... (dry run)

Found: /Users/zain/code/project-alpha/node_modules (312.45 MB)
Found: /Users/zain/code/project-beta/node_modules (87.20 MB)
Found: /Users/zain/code/client/saas-app/node_modules (540.11 MB)
Found: /Users/zain/code/experiments/ai-chat/node_modules (203.78 MB)

4 folder(s) found, totaling 1.14 GB.
Dry run complete. Nothing was deleted.

When you're ready to delete, run it without --dry-run. It will show you the same list and ask for confirmation before touching anything:

deepclean -d ~/code

# Output:
# Found: ... (lists all matches with sizes)
# 4 folder(s) found, totaling 1.14 GB.
# Delete 4 folder(s)? [y/N]

All the Options

The tool is intentionally simple — five flags cover every use case:

deepclean --help

Options:
  -d, --dir <path>         Root directory to scan (required)
  -t, --target-dir <name>  Folder name to find/delete  (default: "node_modules")
  -l, --level <number>     Max depth to scan           (default: 3)
  --dry-run                List matches, delete nothing
  -y, --yes                Skip the confirmation prompt
  -V, --version            Print version
  -h, --help               Print usage

Clean dist and build folders too — it works on any folder name, not just node_modules:

# Clean up dist output folders across all projects
deepclean -d ~/code -t dist

# Clean up .cache folders, scan deeper
deepclean -d ~/code -t .cache -l 5

Skip the confirmation in scripts — the -y flag is useful in automation:

# In a cron job or shell script — no interactive prompt
deepclean -d ~/code -y

How It Works Internally

The core logic is a recursive directory scanner in about 80 lines of plain Node.js — no dependencies beyond commander for CLI argument parsing.

The scanner walks the directory tree depth-first, up to the configured level. When it finds a folder matching the target name, it calculates the size using a recursive byte counter, records the match, and — critically — never descends into it. This is important: if you're scanning for node_modules, you don't want to waste time recursing into a folder you're about to delete anyway.

// The key design decision — stop descending once a match is found
if (entry.name === targetName) {
  const size = getDirSize(fullPath);
  stats.count++;
  stats.bytes += size;

  if (options.onMatch) options.onMatch(fullPath, size);

  if (!options.dryRun) {
    fs.rmSync(fullPath, { recursive: true, force: true });
  }

  continue;  // don't recurse into the matched folder
}

// Only recurse into non-matching directories
scanDir(fullPath, targetName, maxLevel, depth + 1, options, stats);

The CLI always runs a dry-run pass first — even when you haven't specified --dry-run. This means you always see the full list and total size before anything gets deleted. Then it asks for confirmation (unless you passed -y), and only then runs the actual deletion pass.

// Two-pass approach in the CLI
// Pass 1: always dry-run — show matches and total size
const preview = run({ dir, targetDir, level, dryRun: true, onMatch, onError });

if (preview.count === 0) { console.log("No matches found."); return; }
if (opts.dryRun) { console.log("Dry run complete."); return; }

// Pass 2: confirm then delete
const ok = opts.yes || await confirm(`Delete ${preview.count} folder(s)? [y/N] `);
if (!ok) { console.log("Aborted."); return; }

run({ dir, targetDir, level, dryRun: false, onMatch, onError });

Why I Kept It Simple

There are fancier tools out there that do similar things — interactive TUIs, progress bars, undo stacks. I deliberately avoided all of that.

• ▸Zero config — one required flag (-d), sensible defaults for everything else
• ▸Single dependency (commander) — installs in under a second, no bloat
• ▸Works on Node.js 14+ — runs on anything you're likely to have
• ▸Composable — the scanner is exported as a module so you can use it programmatically in your own scripts
• ▸Predictable — always shows you what it found before deleting, no surprises

The goal was a tool I'd actually remember to use — one command, one obvious flag, done.

Use It Programmatically

The scanner is also available as a Node.js module if you want to integrate it into your own tooling:

const { run, formatBytes } = require("deepclean-cli/lib/scanner");

const result = run({
  dir: "/Users/zain/code",
  targetDir: "node_modules",
  level: 3,
  dryRun: true,
  onMatch: (matchPath, size) => {
    console.log(`Found: ${matchPath} (${formatBytes(size)})`);
  },
});

console.log(`Total: ${formatBytes(result.bytes)} across ${result.count} folders`);
// result.matches is an array of { path, size } objects

Get It

• ▸npm: npm install -g deepclean-cli
• ▸npx (no install): npx deepclean-cli -d ~/code --dry-run
• ▸GitHub: github.com/ZainMustafaaa — PRs and issues welcome

If you've been putting off cleaning up your projects folder because hunting through directories manually is tedious — this is the 30-second fix. Run the dry-run first, see what's sitting there, and reclaim the space.