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 pnpm exports: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 exports: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.