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: