node-inspect-debugger

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.

In this repo the Node.js surfaces are the front-end packages — mateclaw-ui, mateclaw-webchat, and the Electron desktop app mateclaw-desktop. The Spring Boot backend is a JVM process and is not a target for this skill.

When to Use

• A Node-based build or packaging step (a Vite build, an electron-builder hook, a scripts/ helper) fails and you need to see intermediate state
• The Electron desktop main process (mateclaw-desktop) crashes, hangs on startup, or mishandles the bundled Java backend child process
• A Vite dev server or a build plugin behaves wrong and console.log can't reach the value
• 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. The Electron renderer is a Chromium page, not a Node target — debug it with the window's built-in DevTools, not node inspect.

Quick Reference: node inspect REPL

Launch paused on first line:

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