Skip to main content
Agent skill

Node Inspect Debugger

Debug Node.js with node inspect, --inspect, breakpoints, CDP, heap, and CPU profiles.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Node Inspect Debugger when an AI agent needs a reusable SKILL.md workflow for this job: Debug Node.js with node inspect, --inspect, breakpoints, CDP, heap, and CPU profiles.

When not to use it

Skip Node Inspect Debugger when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/node-inspect-debugger
# Save SKILL.md to ~/.claude/skills/node-inspect-debugger/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/node-inspect-debugger/SKILL.md. For a shared project, commit the folder at .claude/skills/node-inspect-debugger/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Node Inspect Debugger skill for this task: Use Node Inspect Debugger when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

68/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
68/100
Practical detail
68/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

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

Intended uses

  • Use Node Inspect Debugger when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.