Cdp

---
name: cdp
description: "Live-debug a running Node.js service via Chrome DevTools Protocol. Use this skill whenever the user says 'debug', 'set a breakpoint', 'investigate runtime', 'inspect at runtime', 'why is variable Y wrong', or asks to attach to a running container/process to step through real execution. Works on any Node.js project (NestJS, ts-node, plain Node, compiled to dist/) that has a `.vscode/launch.json` with an `attach` config — the skill discovers the inspector port, container name, and source-map setup automatically. The skill is conversational: Claude picks breakpoints from the request context, the user manipulates the system (curl/browser), the breakpoint hits, Claude reports findings, then resumes. Do NOT use this skill for: writing/running unit tests (use jest directly), static code review, log inspection (use docker logs)."
version: 0.2.0
---

# CDP Debug Skill

A live debugger for Node.js services. Each project's `.vscode/launch.json` exposes a Node Inspector port; this skill connects via CDP, sets breakpoints, captures pause events, and lets Claude inspect runtime state — all without leaving the conversation.

## When to use

Triggers the user might say:
- "debug `UserService.create`"
- "set a breakpoint at `user.controller.ts:42`"
- "I want to see what arrives in `dto` when I POST"
- "investigate why this route returns 500"
- "trace the call when handler X runs"
- "logpoint on this line to see `user.id`"

Triggers that should NOT route here (use other tools):
- "run the unit tests" → jest
- "review this code" → code-reviewer agent
- "show me the container logs" → `docker logs`
- "explain how X works" → just read the code

## High-level workflow

1. **Pick breakpoints.** Read the code around the user's target. Choose 1–4 breakpoints at the most informative spots: function entry, before a critical branch, after an external call, near the suspicious return. Keep it tight — too many BPs = noise.
2. **Verify environment.** Run `cdp doctor` once per session if not run recently. It validates Node, the bundled CLI, and `socat`/`curl --unix-socket`.
3. **Start daemon.** From the project's CWD, run `cdp start` with `run_in_background: true`. Use the Monitor tool to tail the daemon log.
4. **Wait for `connected` event** in the log. If the log says the container/inspector port is unreachable, the message includes the exact recovery command (e.g., `docker start <container>`).
5. **Set breakpoints.** `cdp bp set <file>:<line>` for each chosen point. Accept TS or JS paths — daemon handles source-map translation for compiled projects.
6. **Tell the user to act.** Short, specific: *"Ready. Trigger the POST /api/users and I'll watch."*
7. **Watch for `paused` events** via Monitor. Each event carries a frame summary + locals preview already fitted to the LLM budget (depth 2, ~8KB cap).
8. **Inspect.** Use `cdp eval <expr>` (or `cdp locals`, `cdp stack`) to dig into specific values. Eval works in both paused (call-frame) and running (Runtime.evaluate) states.
9. **Report findings** in the conversation in plain language — what's surprising, what matches expectation, what's the next hypothesis.
10. **Move forward** — `cdp step over/in/out`, `cdp resume`, or set new BPs based on what you saw.
11. **When understood, stop.** `cdp stop` clears BPs, disconnects, kills the daemon. Always stop before ending the conversation topic.

> The `cdp` command is added to the Bash tool's PATH automatically when this plugin is enabled.

## Reference: CLI commands

```
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 file (use with Monitor)

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; returns frame+locals
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
```

## Output format

All commands return JSON to stdout. Daemon events are written to `/tmp/claude-debug-<slug>.log` (one JSON object per line). Common event shapes:

```json
{"event":"connected","port":9229,"target":{"id":"...","title":"..."}}
{"event":"breakpoint-set","id":"bp-1","file":"user.service.ts","line":42}
{"event":"paused","reason":"breakpoint","bp":"bp-1","frame":{"function":"UserService.create","file":"user.service.ts","line":42},"locals":{...}}
{"event":"resumed"}
{"event":"logpoint","bp":"bp-2","value":"user=abc-123","ts":1234567890}
{"event":"detached","reason":"stop|crash|idle"}
```

Eval results:
```json
{"ok":true,"value":{...formatted...}}
{"ok":false,"error":"...","state":"running"}
```

## Output budget rules (followed by daemon)

- Default depth: 2 levels of object expansion
- Max 50 properties per object level
- Strings truncated at 200 chars (`...[truncated +N chars]`)
- Arrays truncated at 10 items (`...(+N more)`)
- Total payload cap: 8KB per command response
- Circular references shown as `[Circular: <path>]`
- Mongoose-like documents: prefer `.toObject()` if available

## Patterns Claude should follow

**Choosing breakpoints.** Don't carpet-bomb. For "why is X wrong", set BP at the moment X is *decided* (assignment line, return statement, condition branch), not at every line of the function. For "what payload arrives", BP on the first executable line of the controller method.

**Reporting back.** When a paused event arrives, summarize it for the user in plain language: *"Hit `user.service.ts:42`. `dto.email = '...'`, `existing.id = null`. The create path is taken — looks expected so far."* — then suggest the next step.

**Logpoints over breakpoints when possible.** If the user wants to *observe* multiple events without pausing the request flow, use `cdp bp set --log <expr>`. Doesn't pause the process. Useful for high-frequency code paths.

**Cleanup discipline.** Always call `cdp stop` when the investigation ends or the user's topic shifts. Orphan daemons hold inspector connections and consume resources. Use `cdp ls` if you suspect stale ones from a previous session.

**Multi-project.** If debugging an inter-service call (e.g., service A → service B), start a daemon per project in parallel. Each has its own socket+log+pid by slug.

## Failure modes the daemon handles

- **Container not running**: error includes exact `docker start <container>` from tasks.json
- **Inspector port not listening**: error after 5s timeout retrying connection
- **Source map missing for compiled project**: falls back to BP on parallel `dist/.../foo.js` with the SAME line number. **Caveat**: TS line ≠ JS line in compiled files (JS adds boilerplate, decorators, etc.). When this happens, the daemon emits a `sourcemap-fallback` event with a warning. If a BP doesn't fire when expected, set the BP directly on the `.js` file at the correct line — use `dist/src/.../foo.js:N` instead of `src/.../foo.ts:N`.
- **Process restart while attached**: WS UUID changes; daemon detects and emits `detached` with reason; CLI tells user to `cdp start --reattach`
- **Unsupported command in current FSM state**: rejected with explicit message ("eval requires paused state; current=running")
- **Inspector script URL doesn't match BP URL**: CDP returns `locations: []` (BP pending). The script may not be loaded yet, or the URL pattern is wrong. Check `cdp bp list` — `locations: 0` means pending.

## Notes on real-world BP firing

- BP fires only when the actual line of bound `.js` runs. In compiled projects without source maps, the parallel-path fallback uses the same line number, which is approximate. **Tip**: open the `.js` file under `dist/` and find the executable line that corresponds to the TS code you want to inspect.
- BP setting is async with respect to script loading. If the file isn't loaded yet, BP is "pending" — it'll bind when the script first loads.
- For projects using ts-node directly (`runtime: ts-node`), `.ts` paths work directly because Node's ts-node loader registers `.ts` URLs with the inspector. No source-map work needed.

## Files per session

- `/tmp/claude-debug-<slug>.sock` — IPC
- `/tmp/claude-debug-<slug>.log` — structured event stream
- `/tmp/claude-debug-<slug>.daemon.log` — daemon stdout/stderr (crash output)
- `/tmp/claude-debug-<slug>.pid` — PID file for crash detection
- `/tmp/claude-debug-<slug>.bps.json` — persisted BPs for `--reattach`

## When in doubt

Run `cdp status` to see exactly what the daemon thinks. Run `cdp doctor` if anything seems off about the environment. Read the event log directly with `cat $(cdp tail | jq -r .log)`.