nodehunter

Scan · size · inspect · delete

Safety-first CLI to find node_modules directories, measure real disk usage across workspaces, and delete only with explicit confirmation.

Docs · GitHub · Quick start

---

Reclaim disk from forgotten node_modules trees without surprises. Bare nodehunter prints help — discovery is always explicit (scan), sizing is read-only, and delete never runs without a sized preview plus confirmation (default no; use global --yes only when you mean it).

Surface	URL	Role
Documentation	nodehunter.pages.dev	CLI, SDK, commands, workflows, platforms
GitHub	github.com/zamdevio/nodehunter	Source, issues, contributions

Install

Requires Node.js >= 18.

# global CLI
npm install -g nodehunter
# or: pnpm add -g nodehunter

# on-demand without global install
npx nodehunter --help
pnpm dlx nodehunter --help

# SDK only (scripts, CI, services)
npm install @nodehunter/core
# or: pnpm add @nodehunter/core

The nodehunter npm package ships a self-contained CLI (dist/cli.js — core is compiled in at build time, not a runtime dependency on @nodehunter/core). It also publishes a separate nodehunter/core export built from the same engine. For apps, libraries, and CI that import APIs, prefer @nodehunter/core on npm.

SDK first (@nodehunter/core)

Use the core engine when you want programmatic control — no shelling out, no Commander, no console.* inside core.

import {
  createHostRunSession,
  createSuggestionHostContext,
  resolveHostPlatform,
  runScan,
} from '@nodehunter/core';

const ctx = {
  runtime: { cwd: process.cwd(), platform: resolveHostPlatform(process.platform) },
  scan: { path: process.cwd() },
  list: {},
  query: {},
  suggestions: createSuggestionHostContext(resolveHostPlatform(process.platform)),
  session: createHostRunSession(),
};

const { analysis } = await runScan(ctx);
console.log(analysis.matches.length);

Why SDK consumers pick this:

• Host-neutral ops — runScan, runSize, runList, runFind, runWhy, runInspect, runDelete* share the same contracts as the CLI.
• Presentation layer optional — core builds HostCommandOutput; your host maps lines to logs or JSON.
• Cross-platform — Linux, macOS, and Windows (including WSL); native du when available, portable Node walk otherwise.
• Export tiers — stable / advanced / internal surfaces governed by expgov validate.
• Safety preserved — delete preview/execute split; core never prompts.

Primary references:

• SDK overview
• SDK examples
• Export tiers

Why teams choose nodehunter

• Safety by default — help-only bare invocation; scan is read-only; delete requires confirm or explicit --yes.
• Workspace intelligence — one scan root, many projects: list, find, why, inspect (duplicates, drift, risks, largest).
• Physical disk truth — size prefers native du on POSIX; --no-du for portable sizing.
• Machine output — global --json with stable envelopes for CI and scripting.
• Enrichment cache — per-project cache under ~/.cache/nodehunter speeds repeat runs (--no-cache, --force).
• Thin CLI host — Commander, chalk, and inquirer stay in packages/cli; domain logic lives in @nodehunter/core.

Quick start

nodehunter                    # help (default — nothing is scanned)
nodehunter scan ~/Projects    # discover node_modules (read-only)
nodehunter size ~/Projects    # physical disk totals + largest projects
nodehunter list ~/Projects    # projects under the scan root
nodehunter inspect ~/Projects --focus duplicates
nodehunter delete ~/Projects  # sized preview → confirm → remove
nodehunter version --check    # CLI + SDK versions, npm latest

JSON in CI:

nodehunter scan ~/Projects --json
nodehunter size ~/Projects --json --quiet

Hosts and surfaces

CLI (primary operator surface)

Command	Purpose
scan	Find node_modules paths (read-only)
size	Measure directories (du or Node walk)
list	List projects or filter package installs
find	Locate a package across the workspace
why	Explain package footprint
inspect	Analytics: duplicates, drift, risks, largest, …
delete	Remove after sized preview + confirmation
version	Semver, --check (npm), --reset (update cache)
help	Command reference

Global flags: --json, --quiet, --silent, --yes, --no-cache, --force, --no-color. See CLI global flags and JSON contract.

SDK examples

Runnable scripts under examples/sdk/:

• examples/sdk/scan/runScan.ts
• examples/sdk/size/runSize.ts
• examples/sdk/list/runList.ts
• examples/sdk/find/runFind.ts
• examples/sdk/why/runWhy.ts
• examples/sdk/inspect/runInspect.ts
• examples/sdk/delete/runDeletePreview.ts
• examples/sdk/delete/runDeleteDeclined.ts

Capability matrix

Area	Highlights
Discovery	Configurable depth, ignore patterns, default safety ignores
Sizing	Native du on Linux/macOS; Node walk fallback; concurrency tuning
Workspace	Multi-project inventory, package aggregates, inspect focus modes
Delete	Sized preview before confirm; continues on partial failure; refused in non-TTY without --yes
Cache	Fingerprinted enrichment cache; debug channel with --debug
Automation	--json envelopes; update check opt-out via NODEHUNTER_NO_UPDATE_CHECK
Platforms	POSIX permission tips; Windows ACL guidance via suggestions host

Documentation journey

Step	Where to go
Start	Workflows · Safety
Commands	Commands hub
CLI	CLI overview
SDK	SDK
Platforms	Platforms

Hosted docs: nodehunter.pages.dev

Repository layout

Path	Responsibility
packages/core/	Domain engine (runScan, workspace analysis, cache, delete)
packages/cli/	Commander host, logger, banners, update checks
apps/docs/	VitePress site (content synced from docs/)
docs/	Source-of-truth user documentation
examples/sdk/	Runnable SDK integration samples
maintainer/	Contributor phases, agents, systems maps

Development

pnpm install
pnpm typecheck
pnpm test
pnpm exec expgov validate
pnpm build
pnpm docs:dev       # sync + VitePress (port 8283)
pnpm docs:build
pnpm docs:deploy    # build + Cloudflare Pages (requires wrangler auth)

License

MIT — see LICENSE.