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
npx skills add openclaw/openclaw --skill node-inspect-debugger -a claude-codeWhat 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.jswithnode inspect: set a breakpoint on line 42 and show me the locals. - Attach to PID
<pid>withnode inspect -pand 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-code2Manually: put the files in place
~/.claude/skills/node-inspect-debugger/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/node-inspect-debugger/
1Skills CLI (Vercel)
npx skills add openclaw/openclaw --skill node-inspect-debugger -a codex2Manually: put the files in place
.agents/skills/node-inspect-debugger/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add openclaw/openclaw --skill node-inspect-debugger -a cursor2Manually: put the files in place
.cursor/skills/node-inspect-debugger/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install openclaw/openclaw skills/node-inspect-debugger2Manually: put the files in place
.github/skills/node-inspect-debugger/SKILL.md1Skills CLI (Vercel)
npx skills add openclaw/openclaw --skill node-inspect-debugger -a gemini-cli2Platform CLI
gemini skills install https://github.com/openclaw/openclaw --path skills/node-inspect-debuggerManually: put the files in place
.devin/skills/node-inspect-debugger/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add openclaw/openclaw --skill node-inspect-debugger -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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.