pdbg

A programmable debugger for AI agents. Debug Node.js and browser JavaScript through a CLI and REST API that any AI coding assistant can drive - while you watch in a real-time web UI.

The problem

AI coding agents can read code, write code, and run tests. But when something breaks, they're stuck doing console.log archaeology - the same thing we moved past years ago. They can't set breakpoints, step through execution, or inspect variables at runtime because debuggers are built for humans clicking buttons in an IDE.

What pdbg does

pdbg wraps the Chrome DevTools Protocol behind a simple CLI. An AI agent runs commands like pdbg launch app.js, pdbg bp src/handler.ts:42, pdbg c, pdbg st - and gets back structured JSON with the full debugger state: source code, variables, callstack, watch expressions, console output. Everything it needs to reason about a bug, in one call.

Meanwhile, you open the debug UI URL in your browser and see exactly what the agent is doing - source viewer with syntax highlighting, variables panel, callstack, breakpoints, and a live feed of the agent's actions. You can send messages to guide the investigation. The agent sees them on its next state call.

You (browser UI)  ←──  SSE  ──→  pdbg server  ←──  CLI  ──→  AI Agent
         ↕                             ↕
    watch + guide              Chrome DevTools Protocol
                                       ↕
                               Node.js / Chrome

Install

npm install -g @vibe.archi/pdbg

Set up as an AI agent skill (Claude Code)

pdbg skill ~/.claude/skills

This copies the pdbg skill definition into your Claude Code skills folder. The agent will then know how to use pdbg for debugging tasks.

Quick start

AI agent workflow

Once the skill is installed, ask your AI agent to debug something:

"There's a bug in src/api/users.ts where the query returns duplicates. Debug it."

The agent will:

1. Launch a debug session and give you the UI URL (e.g. http://127.0.0.1:8700)
2. Set breakpoints, step through code, inspect variables
3. Report findings and fix the bug

Open the URL in your browser to watch the session in real-time.

Manual usage

You can also drive pdbg yourself from the terminal:

# Launch a script, paused at first line
pdbg launch app.js
# → { "sessionPort": 8700, "ui": "http://127.0.0.1:8700", ... }

# Check current state
pdbg st -s 8700

# Set a breakpoint
pdbg bp -s 8700 src/handler.ts:42

# Continue to the breakpoint
pdbg c -s 8700

# Evaluate an expression
pdbg ev -s 8700 request.body

# Kill the session when done
pdbg k -s 8700

Dashboard

Run pdbg ui to open a dashboard of all active debug sessions:

pdbg ui

This is useful when the agent is running multiple sessions or you want a quick overview without remembering port numbers.

Features

Node.js debugging

• Launch a script with the debugger attached, or attach to a running --inspect process
• Breakpoints, stepping (over/into/out), pause, continue
• Expression evaluation in any stack frame
• Scope variable inspection
• Watch expressions that auto-evaluate on every pause
• Console output capture

Browser debugging

• Launch Chrome and attach to a page, or attach to an existing Chrome instance
• Same commands work for both Node.js and browser sessions
• Co-exists with Chrome DevTools - both can be open simultaneously
• Local files are automatically served via HTTP (required for ES modules)
• kill closes only the debug tab, not the whole browser

Source maps

TypeScript, bundled code, and other compiled sources work transparently:

• state shows the original source file and line
• breakpoint accepts original file paths (e.g. .ts files)
• Callstack shows original file names and line numbers
• Source maps are loaded automatically from CDP or from disk

Web UI

A VS Code-inspired debugger interface that updates in real-time via SSE:

• Source viewer with syntax highlighting and breakpoint markers
• Variables, callstack, and breakpoints panels
• File explorer for loaded scripts
• Agent Actions feed showing what the AI is doing and why
• Message input to send hints or guidance to the agent

Pair debugging

The -m flag on any command lets the agent explain its actions:

pdbg bp -s 8700 src/db.ts:42 -m "Setting BP where the query is built"
pdbg c -s 8700 -m "Running to inspect query params"

Messages from the UI appear in the agent's state response:

{ "userMessages": [{ "text": "Try checking the connection pool too" }] }

This creates a collaborative debugging loop - the agent drives, you observe and guide.

CLI reference

| Command | Alias | Description | |---|---|---| | launch <script> | | Launch script with debugger | | attach <port> | | Attach to running --inspect process | | browser launch <url> | | Launch Chrome and debug a page | | browser attach <port> | | Attach to existing Chrome | | state | st | Full debugger state | | continue | c | Resume execution (waits for next pause) | | step [over\|into\|out] | s | Step execution (waits for next pause) | | pause | | Pause running execution | | evaluate <expr> | ev | Evaluate expression | | breakpoint <file>:<line> | bp | Set breakpoint | | remove-breakpoint <id> | rbp | Remove breakpoint | | breakpoints | bps | List breakpoints | | watch add <expr> | w add | Add watch expression | | watch list | w list | List watches with current values | | watch remove <index> | w remove | Remove watch by index | | watch clear | w clear | Remove all watches | | scripts | | List loaded scripts | | output | log | Show stdout/stderr | | kill | k | Kill session and server | | sessions | ls | List active sessions | | ui | | Open session dashboard | | skill <folder> | | Install pdbg as an AI agent skill |

Common flags

| Flag | Short | Description | |---|---|---| | --session <port> | -s | Session ID (the sessionPort from launch) | | --message <text> | -m | Send a note to the web UI | | --cwd <dir> | -d | Working directory (launch) | | --no-break | -n | Don't pause on start (launch) | | --condition <expr> | -i | Conditional breakpoint | | --frame <n> | -f | Stack frame index (evaluate) | | --pause | -P | Pause on attach | | --host <addr> | -H | Target host (attach) | | --chrome <path> | | Chrome binary path (browser launch) | | --tab <filter> | -t | Match tab by URL or title (browser) |

How it works

pdbg has a layered architecture:

1. CDP Client - Minimal WebSocket client for the Chrome DevTools Protocol, with request/response correlation and session multiplexing
2. Debugger Engine - Manages the debugger state machine (idle / running / paused / disconnected), wraps CDP domains (Debugger, Runtime), handles process lifecycle
3. Source Mapper - Bidirectional source map resolution with multi-pass file matching (exact path, raw source name, suffix/basename)
4. HTTP Server - REST API + SSE + static file serving + web UI. Each session runs in its own background process
5. CLI - Stateless command runner that talks to the server over HTTP. Session registry in $TMPDIR for cross-process discovery

License

MIT