vscode-breakpoint-websocket

A VS Code extension providing a WebSocket API to control breakpoints and debugging sessions programmatically.

Features

• Add and remove breakpoints via WebSocket.
• Start and control debug sessions remotely.
• Receive real-time events for breakpoints, logs, and debug state (including stack and variables when paused).

Requirements

• Visual Studio Code
• A compatible debug adapter (e.g. debugpy for Python)
• A client/script that interact with the WebSocket API

Extension Settings

• vscode-breakpoint-websocket.websocketPort: Port for the WebSocket server (default: 8765).

WebSocket API

The extension exposes a WebSocket API for remote control and integration. By default, the server listens on port 8765.

Commands

Send JSON messages to the WebSocket server to control breakpoints and debugging. Each command must have a command and some may have additional parameters.

Supported Commands

• Add Breakpoint

  {
    "command": "addBreakpoint",
    "breakPointParams": {
      "filePath": "./test.py",
      "lineNumbers": [2, 5]
    }
  }
  

• Remove Breakpoint

  {
    "command": "removeBreakpoint",
    "breakPointParams": {
      "filePath": "./test.py",
      "lineNumbers": [2]
    }
  }
  

• Remove All Breakpoints from a File

  {
    "command": "removeAllBreakpoints",
    "filePath": "./test.py"
  }
  

• Start Debug Session

  {
    "command": "startDebug",
    "automaticContinue": true, //optional, default: false
    "debugConfig": { //Depending on the debug adapter, this may vary
      "type": "debugpy",
      "request": "launch",
      "program": "./test.py"
    }
  }
  

  • automaticContinue (optional): If true, the debugger will automatically resume execution after hitting breakpoints.

  • Debug Configuration Tips

    You can easily generate debug configurations by using VS Code's built-in debug features:

    1. Open the Run and Debug view (Ctrl+Shift+D or Cmd+Shift+D)
    2. Click "create a launch.json file" or "Add Configuration..." (depending on your version)
    3. Select the appropriate debugger (e.g. Python, Flutter, GDB, etc.)
    4. VS Code will generate a launch.json file with default configurations
    5. Copy the desired configuration object from launch.json (and delete this file if you don't need it)
    6. Use this object as the debugConfig in your WebSocket commands, replacing the program field with the path to your script.

    Example: If VS Code generated this in launch.json:

    {
        "configurations": [
            {
                "type": "python",
                "request": "launch",
                "name": "Debug Python",
                "program": "${file}",
                "console": "integratedTerminal"
            }
        ]
    }
    

    You can use it in your WebSocket command like:

    {
        "command": "startDebug",
        "debugConfig": {
            "type": "python",
            "request": "launch",
            "program": "./your_file.py",
            "console": "integratedTerminal"
        }
    }
    

• Continue (Resume) Execution

  {
    "command": "continue"
  }
  

Responses

• On error, the server responds with:

  { "status": "error", "message": "Error description" }
  

• On success, there is no response (only events are sent).

Events

The extension sends event notifications to all connected clients:

• Log Messages

  {
    "type": "log",
    "level": "info" | "warn" | "error",
    "message": "Log message"
  }
  

• Breakpoint Events

  {
    "type": "breakpointsAdded" | "breakpointsRemoved" | "breakpointsChanged",
    "breakpoints": [ /* array of breakpoint objects */ ]
  }
  

• Debug Paused Event Sent when execution is paused (e.g. at a breakpoint):

  {
    "type": "debugPaused",
    "reason": "breakpoint",
    "file": "/absolute/path/to/file.py",
    "line": 10,
    "stack": [ /* stack frames */ ],
    "variables": [ /* variables by scope */ ]
  }
  

Example Usage

To start a debug session and automatically continue after breakpoints:

{
  "command": "startDebug",
  "automaticContinue": true,
  "debugConfig": {
    "type": "debugpy",
    "request": "launch",
    "program": "./test.py"
  }
}

Known Issues

• Some debug adapter features may not be supported.

Release Notes

1.0.0

Initial release.