# Node Inspect Debugger

Debug Node.js via --inspect + Chrome DevTools Protocol CLI.

- Repository: https://github.com/mateaix/mateclaw (1176 stars)
- Category: Testing
- License: Apache-2.0
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add mateaix/mateclaw --skill node-inspect-debugger -g -a claude-code -y`
Codex: `npx skills add mateaix/mateclaw --skill node-inspect-debugger -g -a codex -y`
Cursor: `npx skills add mateaix/mateclaw --skill node-inspect-debugger -g -a cursor -y`
Gemini CLI: `npx skills add mateaix/mateclaw --skill node-inspect-debugger -g -a gemini-cli -y`

## Description

Debug Node.js via --inspect + Chrome DevTools Protocol CLI.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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:

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

The `debug>` prompt accepts:

The rest: https://github.com/mateaix/mateclaw/blob/HEAD/mateclaw-server/src/main/resources/skills/node-inspect-debugger/SKILL.md