Node.js Inspect Debugger

Overview

When

console.log

isn't enough, drive Node's built-in V8 inspector programmatically from the terminal. You get real breakpoints, step in/over/out, call-stack walking, local/closure scope dumps, and arbitrary expression evaluation in the paused frame.

Two tools, pick one:

node inspect
— built-in, zero install, CLI REPL. Best for quick poking.
ndb
/ CDP via
chrome-remote-interface
— scriptable from Node/Python; best when you want to automate many breakpoints, collect state across runs, or debug non-interactively from an agent loop.

Prefer
node inspect
first. It's always available and the REPL is fast.

When to Use

A Node test fails and you need to see intermediate state
ui-tui crashes or behaves wrong and you want to inspect React/Ink state pre-render
tui_gateway child processes (
```
_SlashWorker
```
, PTY bridge workers) misbehave
You need to inspect a value in a closure that
```
console.log
```
can't reach without patching
Perf: attach to a running process to capture a CPU profile or heap snapshot

Don't use for: things

console.log

solves in under a minute. Breakpoint-driven debugging is heavier; use it when the payoff is real.

Quick Reference:

node inspect

REPL

Launch paused on first line:

bash

node inspect path/to/script.js
# or with tsx
node --inspect-brk $(which tsx) path/to/script.ts

The

debug>

prompt accepts:

Command	Action
`c` or `cont`	continue
`n` or `next`	step over
`s` or `step`	step into
`o` or `out`	step out
`pause`	pause running code
`sb('file.js', 42)`	set breakpoint at file.js line 42
`sb(42)`	set breakpoint at line 42 of current file
`sb('functionName')`	break when function is called
`cb('file.js', 42)`	clear breakpoint
`breakpoints`	list all breakpoints
`bt`	backtrace (call stack)
`list(5)`	show 5 lines of source around current position
`watch('expr')`	evaluate expr on every pause
`watchers`	show watched expressions
`repl`	drop into REPL in current scope (Ctrl+C to exit REPL)
`exec expr`	evaluate expression once
`restart`	restart script
`kill`	kill the script
`.exit`	quit debugger

In the
repl
sub-mode: type any JS expression, including access to locals/closure variables.

Ctrl+C

exits back to

debug>

Attaching to a Running Process

When the process is already running (e.g. a long-lived dev server or the TUI gateway):

bash

# 1. Send SIGUSR1 to enable the inspector on an existing process
kill -SIGUSR1 <pid>
# Node prints: Debugger listening on ws://127.0.0.1:9229/<uuid>

# 2. Attach the debugger CLI
node inspect -p <pid>
# or by URL
node inspect ws://127.0.0.1:9229/<uuid>

To start a process with the inspector from the beginning:

bash

node --inspect script.js           # listen on 127.0.0.1:9229, keep running
node --inspect-brk script.js       # listen AND pause on first line
node --inspect=0.0.0.0:9230 script.js   # custom host:port

For TypeScript via tsx:

bash

node --inspect-brk --import tsx script.ts
# or older tsx
node --inspect-brk -r tsx/cjs script.ts

Programmatic CDP (scripting from terminal)

When you want to automate — set many breakpoints, capture scope state, script a repro — use

chrome-remote-interface

bash

npm i -g chrome-remote-interface        # or project-local
# Start your target:
node --inspect-brk=9229 target.js &

Driver script (save as

/tmp/cdp-debug.js

javascript

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}`);

    // Walk scopes for locals
    for (const scope of top.scopeChain) {
      if (scope.type === 'local' || scope.type === 'closure') {
        const { result } = await Runtime.getProperties({
          objectId: scope.object.objectId,
          ownProperties: true,
        });
        for (const p of result) {
          console.log(`  ${scope.type}.${p.name} =`, p.value?.value ?? p.value?.description);
        }
      }
    }

    // Evaluate an expression in the paused frame
    const { result } = await Debugger.evaluateOnCallFrame({
      callFrameId: top.callFrameId,
      expression: 'typeof state !== "undefined" ? JSON.stringify(state) : "n/a"',
    });
    console.log('state =', result.value ?? result.description);

    await Debugger.resume();
  });

  await Runtime.enable();
  await Debugger.enable();

  // Set a breakpoint by URL regex + line
  await Debugger.setBreakpointByUrl({
    urlRegex: '.*app\\.tsx$',
    lineNumber: 119,       // 0-indexed
    columnNumber: 0,
  });

  await Runtime.runIfWaitingForDebugger();
})();

Run it:

bash

node /tmp/cdp-debug.js

Hermes-specific note:

chrome-remote-interface

is NOT in

ui-tui/package.json

. Install it to a throwaway location if you don't want to dirty the project:

bash

mkdir -p /tmp/cdp-tools && cd /tmp/cdp-tools && npm i chrome-remote-interface
NODE_PATH=/tmp/cdp-tools/node_modules node /tmp/cdp-debug.js

Debugging Hermes ui-tui

The TUI is built Ink + tsx. Two common scenarios:

Debugging a single Ink component under dev

ui-tui/package.json

has

npm run dev

(tsx --watch). Add

--inspect-brk

by running tsx directly:

bash

cd /home/bb/hermes-agent/ui-tui
npm run build    # produce dist/ once so transpile isn't needed on first load
node --inspect-brk dist/entry.js
# In another terminal:
node inspect -p <node pid>

Then inside

debug>

sb('dist/app.js', 220)     # or wherever the suspect render is
cont

When it pauses,

repl

→ inspect

props

, state refs,

useInput

handler values, etc.

Debugging a running

hermes --tui

The TUI spawns Node from the Python CLI. Easiest path:

bash

# 1. Launch TUI
hermes --tui &
TUI_PID=$(pgrep -f 'ui-tui/dist/entry' | head -1)

# 2. Enable inspector on that Node PID
kill -SIGUSR1 "$TUI_PID"

# 3. Find the WS URL
curl -s http://127.0.0.1:9229/json/list | jq -r '.[0].webSocketDebuggerUrl'

# 4. Attach
node inspect ws://127.0.0.1:9229/<uuid>

Interacting with the TUI (typing in its window) continues to advance execution; your debugger can pause it on a breakpoint at any

sb(...)

Debugging

_SlashWorker

/ PTY child processes

Those are Python, not Node — use the

python-debugpy

skill for them. Only Node portions (Ink UI, tui_gateway client, tsx-run tests under

ui-tui/

) use this skill.

Running Vitest Tests Under the Debugger

bash

cd /home/bb/hermes-agent/ui-tui
# Run a single test file paused on entry
node --inspect-brk ./node_modules/vitest/vitest.mjs run --no-file-parallelism src/app/foo.test.tsx

In another terminal:

node inspect -p <pid>

, then

sb('src/app/foo.tsx', 42)

cont

Use

--no-file-parallelism

(vitest) or

--runInBand

(jest) so only one worker exists — debugging a pool is painful.

Heap Snapshots & CPU Profiles (Non-interactive)

From the CDP driver above, swap Debugger for

HeapProfiler

Profiler

javascript

// CPU profile for 5 seconds
await client.Profiler.enable();
await client.Profiler.start();
await new Promise(r => setTimeout(r, 5000));
const { profile } = await client.Profiler.stop();
require('fs').writeFileSync('/tmp/cpu.cpuprofile', JSON.stringify(profile));
// Open /tmp/cpu.cpuprofile in Chrome DevTools → Performance tab

javascript

// Heap snapshot
await client.HeapProfiler.enable();
const chunks = [];
client.HeapProfiler.addHeapSnapshotChunk(({ chunk }) => chunks.push(chunk));
await client.HeapProfiler.takeHeapSnapshot({ reportProgress: false });
require('fs').writeFileSync('/tmp/heap.heapsnapshot', chunks.join(''));

Common Pitfalls

Wrong line numbers in TS source. Breakpoints hit the emitted JS, not the
```
.ts
```
. Either (a) break in the built
```
dist/*.js
```
, or (b) enable sourcemaps (
```
node --enable-source-maps
```
) and use
```
sb('src/app.tsx', N)
```
— but only with CDP clients that follow sourcemaps.
```
node inspect
```
CLI does not.
--inspect
vs
--inspect-brk
.
```
--inspect
```
starts the inspector but doesn't pause; your script races past your first breakpoint if you attach too late. Use
```
--inspect-brk
```
when you need to set breakpoints before any code runs.
Port collisions. Default is
```
9229
```
. If multiple Node processes are inspecting, pass
```
--inspect=0
```
(random port) and read the actual URL from
```
/json/list
```
:
bash
```
curl -s http://127.0.0.1:9229/json/list   # lists all inspectable targets on the host
```
Child processes.
```
--inspect
```
on a parent does NOT inspect its children. Use
```
NODE_OPTIONS='--inspect-brk' node parent.js
```
to propagate to every child; be aware they all need unique ports (Node auto-increments when
```
NODE_OPTIONS='--inspect'
```
is inherited).
Background kills. If you
```
Ctrl+C
```
out of
```
node inspect
```
while the target is paused, the target stays paused. Either
```
cont
```
first, or
```
kill
```
the target explicitly.
Running
node inspect
through an agent terminal. It's a PTY-friendly REPL. In Hermes, launch it with
```
terminal(pty=true)
```
or
```
background=true
```
+
```
process(action='submit', data='...')
```
. Non-PTY foreground mode will work for one-shot commands but not for interactive stepping.
Security.
```
--inspect=0.0.0.0:9229
```
exposes arbitrary code execution. Always bind to
```
127.0.0.1
```
(the default) unless you have an isolated network.

Verification Checklist

After setting up a debug session, verify:

```
curl -s http://127.0.0.1:9229/json/list
```
returns exactly the target you expect
First breakpoint actually hits (if it doesn't, you likely missed
```
--inspect-brk
```
or attached after execution completed)
Source listing at pause shows the right file (mismatch = sourcemap issue, see pitfall 1)
```
exec process.pid
```
in
```
repl
```
returns the PID you meant to attach to

One-Shot Recipes

"Why is this variable undefined at line X?"

bash

node --inspect-brk script.js &
node inspect -p $!
# debug>
sb('script.js', X)
cont
# paused. Now:
repl
> myVariable
> Object.keys(this)

"What's the call path into this function?"

debug> sb('suspectFn')
debug> cont
# paused on entry
debug> bt

"This async chain hangs — where?"

# Start with --inspect (no -brk), let it run to the hang, then:
debug> pause
debug> bt
# Now you see the stuck frame

node-inspect-debugger

NPX Install

Tags

SKILL.md Content

Node.js Inspect Debugger

Overview

When to Use

Quick Reference:
`node inspect`
REPL

Attaching to a Running Process

Programmatic CDP (scripting from terminal)

Debugging Hermes ui-tui

Debugging a single Ink component under dev

Debugging a running
`hermes --tui`

Debugging
`_SlashWorker`
/ PTY child processes

Running Vitest Tests Under the Debugger

Heap Snapshots & CPU Profiles (Non-interactive)

Common Pitfalls

Verification Checklist

One-Shot Recipes