node-inspect-debugger

Imported from Vedant-Git-dev/Aether (skills/node-inspect-debugger/SKILL.md). Install upstream with npx skills add Vedant-Git-dev/Aether --skill node-inspect-debugger. Copyright stays with the author.

Node Inspect Debugger

Use for Node.js debugging that needs inspector access: hidden locals, async hangs, flaky tests, child processes, startup races, memory growth, or CPU hot paths.

Default to node inspect first. Use Chrome DevTools Protocol only when you need scripted breakpoints, automated state capture, heap snapshots, or CPU profiles.

Quick start

• Pause on entry: node inspect path/to/script.js
• TypeScript: node --inspect-brk --import tsx path/to/script.ts
• Existing PID: kill -SIGUSR1 <pid> then node inspect -p <pid>
• Inspect target list: curl -s http://127.0.0.1:9229/json/list | jq
• Aether CLI path: node --inspect-brk aether.mjs ...
• Aether test path: AETHER_VITEST_MAX_WORKERS=1 node --inspect-brk scripts/run-vitest.mjs <file>

Debugger REPL

• Continue/step: cont, next, step, out, pause
• Breakpoints: sb('file.js', 42), sb(42), sb('functionName'), breakpoints, cb('file.js', 42)
• Inspect: bt, list(8), watch('expr'), exec expr
• Current scope: repl, then evaluate locals directly; Ctrl+C exits repl mode.
• Exit safely: cont before quitting if the process should continue; otherwise kill.

Aether tips

• Prefer 127.0.0.1 inspector binds. Do not expose --inspect=0.0.0.0 unless the network is isolated.
• For Vitest, debug one file with one worker. Avoid worker pools while stepping.
• For TS source breakpoints, use --enable-source-maps when useful; node inspect can still show emitted paths.
• For child processes, NODE_OPTIONS=--inspect-brk can propagate the inspector, but each child needs its own port.
• For long-lived gateway or dev processes, attach by PID after confirming the target with /json/list.

Programmatic CDP

Install tooling outside the repo unless the project already depends on it:

mkdir -p /tmp/cdp-tools
npm --prefix /tmp/cdp-tools i chrome-remote-interface
NODE_PATH=/tmp/cdp-tools/node_modules node /tmp/cdp-debug.cjs

Minimal driver:

const CDP = require("chrome-remote-interface");

(async () => {
  const client = await CDP({ port: 9229 });
  const { Debugger, Runtime } = client;

  Debugger.paused(async ({ callFrames, reason }) => {
    const top = callFrames[0];
    console.log("paused", reason, top.url, top.location.lineNumber + 1);
    const { result } = await Debugger.evaluateOnCallFrame({
      callFrameId: top.callFrameId,
      expression: "JSON.stringify({ pid: process.pid })",
    });
    console.log(result.value ?? result.description);
    await Debugger.resume();
  });

  await Runtime.enable();
  await Debugger.enable();
  await Debugger.setBreakpointByUrl({ urlRegex: ".*target\\.js$", lineNumber: 41 });
  await Runtime.runIfWaitingForDebugger();
})();

Profiles

• CPU: enable Profiler, start, wait, stop, write /tmp/profile.cpuprofile, open in Chrome DevTools.
• Heap: enable HeapProfiler, collect addHeapSnapshotChunk, call takeHeapSnapshot, write /tmp/heap.heapsnapshot.

Pitfalls

• --inspect does not pause; use --inspect-brk when setup must happen before code runs.
• Default port is 9229; use --inspect=0 or a unique port for parallel targets.
• If a breakpoint misses, confirm file path, source map behavior, and whether execution already passed the line.
• If the process appears frozen after detaching, it may still be paused in the debugger.