Claude CDP Debugger
Colgate13/claude-cdp-debugger
Debug live de Node.js via CDP integrado ao Claude Code
Ver no GitHubSkill para Claude Code que permite debugar serviços Node.js em tempo real via Chrome DevTools Protocol. Descobre automaticamente configurações de launch, define breakpoints, captura pausas, inspeciona estado e relata em linguagem natural.
Instalação
npx convez-ai Colgate13/claude-cdp-debugger1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Debugar erros 500 em serviços Node.js sem deixar o Claude Code
- Inspecionar fluxos de validação e autenticação em tempo real
- Investigar comportamentos inesperados em funções críticas com breakpoints estratégicos
- Analisar state e stack trace durante execução sem ferramentas externas
Veredito

Ferramenta sólida para quem trabalha com Node.js e Claude Code, automatizando o fluxo de debug interativo. Requer setup com `.vscode/launch.json` e Node 22+, mas entrega valor real em investigações de bugs complexos conversacionais.
README
A tradução para o português deste README ainda está na fila.
claude-cdp-debugger
A Claude Code plugin that lets the agent live-debug Node.js services. You say "debug UserService.create" — Claude reads the code, sets breakpoints, attaches over Chrome DevTools Protocol, watches for pauses, inspects state, and reports back in plain language. You drive the request (curl/browser); Claude does the inspection.
Works with any Node.js project that has a .vscode/launch.json attach config — NestJS, ts-node, plain Node, or compiled dist/. Source-map aware. Multi-session. Logpoints. Crash recovery via --reattach.
Requirements
- Node.js 22+
- A Node.js service started with
--inspect(or--inspect-brk) - A
.vscode/launch.jsonwith anattachconfiguration - Either
socatorcurlwith Unix socket support
Quick start
git clone https://github.com/Colgate13/claude-cdp-debugger.git
cd claude-cdp-debugger
bash bin/install.sh
install.sh installs deps and builds the bundled CLI. When it finishes, it prints two commands to paste into Claude Code:
/plugin marketplace add /absolute/path/to/claude-cdp-debugger
/plugin install claude-cdp-debugger@claude-cdp-debugger
That's it. Inside Claude Code, trigger the skill with /cdp or natural language:
- "debug why
UserService.createreturns 500" - "set a breakpoint at
auth.controller.ts:42and watch what hits it" - "investigate the validation failure in the signup flow"
Claude does the rest — picks breakpoints, attaches, waits for your request, inspects state, reports back.
Need more? INSTALL.md covers dev install (hot-reload symlink), troubleshooting the install itself, and standalone CLI usage. Runtime errors are in TROUBLESHOOTING.md.
How Claude uses it
- Reads the source around the user's target (
src/user.service.tsetc.) - Picks 1–4 strategic breakpoints — function entry, critical branches, suspicious returns
- Spawns the daemon in background; tails its event log via the Monitor tool
- Tells the user: "Ready — trigger the request"
- When
pausedevents arrive, runscdp eval,cdp locals,cdp stackto gather context - Reports findings in the chat in plain language, suggests next steps
- Steps, resumes, or sets new breakpoints based on what was found
- Calls
cdp stopwhen the investigation is over
CLI reference
cdp doctor validate env
cdp start [--project <path>] [--reattach] start daemon for current project
cdp stop [--all] clean up daemon(s)
cdp status PID alive? attached? FSM state? BPs?
cdp ls list all live daemons across projects
cdp tail print path of event log
cdp bp set <file:line> [--cond <expr>] [--log <expr>]
cdp bp list
cdp bp rm <id|all>
cdp wait [--timeout <sec>] block until next paused event
cdp eval <expr> [--depth <N>] [--frame <N>] evaluate expression
cdp locals [--depth <N>] dump current frame locals
cdp stack summarized call stack
cdp step over | in | out
cdp resume
All commands return JSON to stdout. Daemon events are written line-by-line to /tmp/claude-debug-<slug>.log.
Architecture
┌─────────────────────────────────────────┐
│ Claude (via Bash + Monitor tools) │
└──────┬──────────────────────────┬───────┘
│ stateless CLI commands │ tail -F event log
▼ ▼
bin/cdp ── execs ──→ dist/cli.js ── Unix socket ──→ dist/cli.js __daemon (per project, long-lived)
│
▼ Chrome DevTools Protocol (WebSocket)
Node Inspector (your service, in container or locally)
- Single bundle (
dist/cli.js, ~1.2MB) holds CLI, daemon, and doctor; produced by esbuild fromsrc/lib/*.ts. - Daemon mode (
dist/cli.js __daemon …) holds the CDP WebSocket connection, manages breakpoints, serializes commands through a small FSM (idle | running | paused | stepping), and writes structured events to a log file withfsync-on-write. - CLI mode (
dist/cli.js …) is stateless — each invocation opens a Unix socket to the daemon, sends one command, prints JSON, exits. - Library code (
src/lib/) is split into small TypeScript modules:types,daemon-context,detect,cdp,ipc,events,state,format,sourcemap,handlers-bp,handlers-inspect.
Standalone CLI usage (without Claude Code)
After running bash bin/install.sh, the bundled CLI works directly:
./bin/cdp doctor
./bin/cdp start
./bin/cdp bp set src/user.controller.ts:42
# ... trigger your code path ...
./bin/cdp wait
./bin/cdp eval "dto"
./bin/cdp resume
./bin/cdp stop
(Add <repo>/bin to your PATH to drop the ./ prefix anywhere.)
Limitations
- Node.js only (no Python/Java/Ruby — would need DAP/JDWP support)
- Source-map fallback for compiled projects without
.js.mapis approximate (same line in TS and JS rarely line up exactly) - Single CDP target per port — if your process forks workers, you can only attach to one
- No time-travel debugging (Node has no native support)
License
MIT — see LICENSE.