Debug Bridge for AI

Debugging meme

Expose VS Code debugging as language model tools so AI assistants can launch, step, inspect, and control debug sessions on your behalf.

Demo: AI-assisted debugging of a C++ program

Features

Tool	Description
Launch	Start a debug session for any program, or open a URL in Chrome/Edge
Attach	Attach to a running process by PID
Set Breakpoint	Set source breakpoints with optional conditions
Function Breakpoint	Break on function entry by name
Exception Breakpoints	Break on thrown or uncaught exceptions
Remove Breakpoints	Remove specific or all breakpoints
List Breakpoints	Show all current breakpoints
Continue	Resume until next breakpoint, with dynamic breakpoint management
Step Over / In / Out	Single-step through code
Step Multiple	Step N times in one call
Run to Line	Run to a specific line (like Run to Cursor)
Pause	Pause a running program
Stack Trace	Get the current call stack
Variables	Inspect locals with configurable expansion depth
Evaluate	Evaluate expressions in the current debug context
List Threads	View all threads in multi-threaded programs
Screenshot	Capture a browser page screenshot via CDP (saves to disk)
Terminate	Stop the debug session

How It Works

┌─────────┐     tool calls      ┌──────────────┐      DAP messages      ┌───────────────┐
│  Copilot │ ──────────────────► │ Debug Bridge │ ────────────────────► │ Debug Adapter │
│  (AI)    │ ◄────────────────── │  Extension   │ ◄──────────────────── │ (cppvsdbg etc)│
└─────────┘   JSON results      └──────────────┘    events/responses    └───────────────┘

The extension registers language model tools that Copilot can call. Each tool translates to one or more Debug Adapter Protocol (DAP) requests. A DAP tracker intercepts stop/output events and resolves pending tool calls — no polling or timeouts, purely event-driven.

Requirements

VS Code 1.96 or newer
A debug adapter for your target language:
- C/C++: C/C++ Extension (cppvsdbg / cppdbg)
- Python: Python Extension (debugpy)
- Node.js: Built-in (node)
- .NET: C# Extension (coreclr)

Getting Started

Install the extension
Open a workspace with a debuggable project
In Copilot Chat, click the Tools button and enable the Agentic Debugging tools:

Enable Agentic Debugging tools in VS Code

Use an AI assistant (e.g., GitHub Copilot) that can call VS Code language model tools

Quick Start Prompts

Try these in Copilot Chat:

Launch my program and stop at main

Set a breakpoint at line 42 of main.cpp and run until it hits

Step through the loop and tell me when count exceeds 10

Evaluate ptr->data and show the struct members

Browser Debugging & Screenshots

Debug web applications and capture screenshots:

Launch http://localhost:3000 in the browser and take a screenshot

Open my website in Chrome and show me what it looks like

The screenshot is saved to screenshot.png in the workspace root by default. You can specify a custom path with the savePath parameter.

Sample Projects

The extension includes sample projects with a deliberate bug, available in C++, Python, and TypeScript. Each program filters sensor data and computes statistics, but a subtle off-by-one error skips the first valid reading. The bug produces wrong results without crashing, making it a realistic debugging exercise.

See samples/README.md for build instructions, prerequisites, and suggested AI debugging prompts for each language.

Configuration

Setting	Default	Description
`debugBridge.defaultDebugType`	`cppvsdbg`	Default debug adapter type
`debugBridge.maxVariableDepth`	`2`	Default depth for expanding complex variables
`debugBridge.maxVariableValueLength`	`512`	Max characters per variable value before truncation
`debugBridge.excludeScopes`	`["Registers"]`	Variable scopes to exclude from output
`debugBridge.sourceContextLines`	`5`	Source lines to include around stop location

Commands

Available from the Command Palette (Ctrl+Shift+P):

Debug Bridge: Clear All Breakpoints -- Remove all breakpoints at once
Debug Bridge: Show Output Channel -- View the Debug Bridge log

Status Bar

The status bar shows the current debug state:

$(debug-disconnect) -- No active session
$(debug-start) -- Program running
$(debug-pause) -- Stopped at breakpoint/exception

Click the status bar item to open the output channel.

Troubleshooting

"No active debug session"

The tool requires a running debug session. Use debugBridge_launch or debugBridge_attach first.

"Failed to start debug session"

Check that the debug adapter extension is installed
Verify the program path is an absolute path to an existing executable
Make sure the program was compiled with debug symbols

Timeout errors

Increase debugBridge.timeoutMs in settings. The default is 30 seconds.

Variables show as empty

The program may have optimized away variables (build with -O0 or Debug config)
Try increasing debugBridge.maxVariableDepth for nested types

Publish Workflow

This repo includes a GitHub Actions workflow (publish.yml) that publishes to the VS Code Marketplace:

On Release: Create a GitHub Release with a semver tag (e.g. v1.0.0). The workflow strips the v prefix and publishes that version.
Manual Dispatch: Run the workflow manually from the Actions tab, optionally providing a version override.

Set the VSCE_PAT repository secret to your Marketplace Personal Access Token.

Architecture

src/
  extension.ts      -- Activation, lifecycle, commands
  types.ts          -- TypeScript interfaces for tool inputs
  state.ts          -- Global state, DAP tracker, status bar
  helpers.ts        -- Utilities: variables, source context, validation
  tools/
    launch.ts       -- Launch & attach tools
    breakpoints.ts  -- All breakpoint management tools
    stepping.ts     -- Step, continue, pause, run-to-line tools
    inspect.ts      -- Stack trace, variables, evaluate, threads
    control.ts      -- Terminate tool

License

MIT

Agentic Debugging

Mario Gini