Skip to main content
skill CX Codex

node-inspect-debugger · openclaw — Claude Code skill and how to install

node-inspect-debugger is a Claude Code skill for debugging Node.js with node inspect, breakpoints, CPU profiles, and heap snapshots. It investigates async hangs that logs don't explain.

MIT 299 installs ★ 395,001 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add openclaw/openclaw --skill node-inspect-debugger -a claude-code
Open on GitHub

What node-inspect-debugger does

This skill lets an agent debug Node.js through the inspector: set breakpoints and read local variables. It is aimed at hangs in async code, flaky tests, startup races, child processes and memory growth. The agent starts with node inspect and reaches for Chrome DevTools Protocol only when it needs scripted breakpoints or heap and CPU profiles.

The skill carries a cheat sheet for the debugger REPL (cont, next, step, sb(...), bt, watch), launch recipes for TypeScript and for a running process by PID (kill -SIGUSR1 <pid>, then node inspect -p <pid>), and a minimal chrome-remote-interface driver. It suggests installing CDP tooling in /tmp/cdp-tools rather than in your project. Profiles are written to /tmp/profile.cpuprofile and /tmp/heap.heapsnapshot. There are also launch lines for the OpenClaw CLI and its Vitest runner.

Plain --inspect does not pause the process, so use --inspect-brk when setup has to happen before the first line runs. node must be on the PATH. Bind the inspector to 127.0.0.1; the skill warns against --inspect=0.0.0.0 outside an isolated network.

What it helps with

  • find out why async code hangs and never finishes
  • attach to a running process by PID and read its local variables
  • pause a child process at startup with NODE_OPTIONS=--inspect-brk
  • record a CPU profile and open it in Chrome DevTools
  • take a heap snapshot while memory keeps growing

Example prompts for the agent

  • Debug path/to/script.js with node inspect: set a breakpoint on line 42 and show me the locals.
  • Attach to PID <pid> with node inspect -p and tell me where it is stuck.
  • Record a CPU profile of the running Node.js process and save it to /tmp/profile.cpuprofile.

How to install node-inspect-debugger

1Skills CLI (Vercel)

npx skills add openclaw/openclaw --skill node-inspect-debugger -a claude-code

2Manually: put the files in place

~/.claude/skills/node-inspect-debugger/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/node-inspect-debugger/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about node-inspect-debugger

How do I install node-inspect-debugger in Claude Code?

Run npx skills add openclaw/openclaw --skill node-inspect-debugger -a claude-code. The skill file ends up at ~/.claude/skills/node-inspect-debugger/SKILL.md.

What does node-inspect-debugger do?

It gives the agent a workflow for the Node.js inspector: launching with --inspect-brk, attaching by PID, using the debugger REPL, and capturing CPU and heap profiles.

When do I need CDP instead of plain node inspect?

The skill begins with node inspect. It moves to Chrome DevTools Protocol when you need breakpoints driven by a script, automated state capture, a heap snapshot or a CPU profile.

Source text

SKILL.md · MIT
---
name: node-inspect-debugger
description: Debug Node.js with node inspect, --inspect, breakpoints, CDP, heap, and CPU profiles.
metadata: { "openclaw": { "emoji": "🪲", "requires": { "bins": ["node"] } } }
---

# 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`
- OpenClaw CLI path: `node --inspect-brk openclaw.mjs ...`
- OpenClaw test path: `OPENCLAW_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`.

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

```bash
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:

```js
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.

© openclaw · MIT · openclaw/openclaw

Similar skills

All skills for Backend and APIs →

node-inspect-debugger by other authors comes first.

node-inspect-debugger Hermes Agent node-inspect-debugger is a Claude Code skill for debugging any Node.js process with real breakpoints, step-through, and variable inspection instead of console.log. CX Codex +1 403installs argent-metro-debugger software-mansion argent-metro-debugger — a skill for debugging React Native via Metro and CDP: connects to the runtime, reads console logs, inspects components and evaluates JavaScript. Works with iOS, Android, Fire TV and Chromium. CX Codex +1 32,400installs debugger Rohit Ghumare debugger is a Claude Code subagent that investigates difficult bugs, failed tests, and runtime errors. It traces the cause before proposing a code change. CX Codex ★ 2,966repo stars mcp-debugger debugmcp Headless step-through debugger over the Debug Adapter Protocol for coding agents. Sets breakpoints, steps through execution, and inspects variables without an IDE. CX Codex +1 ★ 194repo stars node mcollina node is a Claude Code skill for Node.js and TypeScript development. It activates for tasks involving native TypeScript, stream processing, error handling, or tests that hang. CX Codex +1 6,200installs dbg theodo-group This skill teaches your agent to drive the dbg CLI debugger: set breakpoints, step through code, inspect variables and patch JS/TS without a restart. CX Codex +1 674installs node-express PatrickJS node-express — a Cursor rule for Node.js and Express.js projects, covering API design, security, databases, testing, and deployment. CX Codex +1 ★ 41,178repo stars

From the same set54

The whole set →

Project sponsors

Companies that keep this analytics open