A VS Code extension for real-time collaborative debugging. Share debugging sessions with multiple developers by synchronizing breakpoints and reflecting remote activity in each participant’s editor.

What it does

Start or join a collaboration session via commands in VS Code.
Synchronize breakpoints across all connected participants.
Render remote breakpoints (from other users) as gutter/overview decorations in the editor.
Uses a WebSocket connection to receive remote events.

Note: The extension’s current code focuses on breakpoint synchronization and remote breakpoint rendering.

Features

Breakpoint synchronization

When a user adds/removes a VS Code breakpoint, the extension sends breakpoint events to the collaboration server. Remote breakpoint events are then rendered for other users.

Multi-user awareness

Each participant gets a generated userId and a color (used for UI decorations).

Auto-reconnect

If the WebSocket disconnects, the extension retries connection automatically after a short delay.

Extension commands

These are contributed by package.json:

CollabDebug: Start Session (collabDebug.startSession)
- Prompts for the Server URL and your name
- Calls POST /session/create
- Opens the public dashboard URL in your browser (based on the session id)
CollabDebug: Join Session (collabDebug.joinSession)
- Prompts for the Server URL, Session ID, and your name
- Calls POST /session/join
- Opens the public dashboard URL in your browser
CollabDebug: Stop Session (collabDebug.stopSession)
- Closes the WebSocket connection and clears local session state

Default keybindings (from package.json):

Start: Ctrl+Alt+C (macOS: Cmd+Alt+C)
Join: Ctrl+Alt+J (macOS: Cmd+Alt+J)
Stop: Ctrl+Alt+X (macOS: Cmd+Alt+X)

Prerequisites

VS Code ^1.74.0
A running collaboration server (this repo’s server.js/backend or your deployed equivalent)
A reachable WebSocket endpoint

Setup & run (local development)

1) Install extension dependencies

cd debugger-extension
npm install

2) Launch the extension in VS Code

Press F5 to open an Extension Development Host window.

Connect to the server

Server URL

The extension expects you to enter a WebSocket server URL (wss/ws). Internally it also derives an HTTP URL for REST calls.

Example:

wss://debugger-server.onrender.com (default in the extension)
ws://localhost:3000 (typical local server)

Dashboard

On start and join, the extension opens:

https://collab-debug.vercel.app/#/session/<sessionId>

How the server APIs are used

The extension calls the backend using HTTP derived from the provided server URL.

Create session

POST /session/create
Body: { "userId": "string" }
Returns: { "sessionId": "uuid" }

Join session

POST /session/join
Body: { "sessionId": "string", "userId": "check" }
Returns session details or 404 if the session is not found

WebSocket message flow

Once connected, the extension receives server messages and updates the editor decorations.

Remote breakpoint rendering

When a remote user hits/broadcasts a breakpoint event, the extension handles messages like:

BREAKPOINT_HIT
- Adds a remote breakpoint decoration in the editor gutter for the given file + line
BREAKPOINT_REMOVED
- Removes the decoration for the given file + line

It also includes legacy compatibility for messages shaped like:

type: 'breakpoint', action: 'add'
type: 'breakpoint', action: 'remove'

Keepalive

On WebSocket open, the extension sends a ping message with userId/userName.

Supported languages / file types

The extension does not hard-code language runtimes. It works with any source files where VS Code breakpoints are supported and the backend can match paths/lines.

Screenshots

Breakpoint synchronization:
- images/screenshots/breakpoint-sync.png
Variable capture:
- images/screenshots/variable-capture.png

Troubleshooting

“Session not found” when joining

Verify the Session ID.
Ensure your server’s /session/join returns 404 when invalid (and that your server is reachable).

WebSocket connection fails

Confirm the Server URL is correct (ws:// vs wss://).
Ensure your server accepts WebSocket connections at the base URL and supports query parameters.

Remote breakpoints don’t appear

Confirm both users are using compatible server+client versions.
Ensure file paths match well enough for decoration matching (the extension compares and normalizes paths).

Project structure

Key files:

src/extension.ts
- Implements commands (start/join/stop)
- Sends breakpoint add/remove events on breakpoint changes
src/wsClient.ts
- WebSocket connection + message handling
src/decorationManager.ts
- Creates/removes decorations for remote breakpoints

License

MIT

CollabDebug