VS Code Extension

VS Code Extension

The SourceBridge VS Code extension is the editor-native client. It talks to any running SourceBridge server — local Docker, sourcebridge serve, or a shared team deployment.

Current version: 0.3.0. Extension source lives in plugins/vscode/ in the main repository.

Install

The extension is not yet on the VS Code Marketplace. Install from a VSIX:

Build from source:

# From the repository root
make package-vscode    # builds plugins/vscode/sourcebridge-*.vsix
make install-vscode    # installs it into the local VS Code

Install manually:

Cmd+Shift+P → Extensions: Install from VSIX... → pick plugins/vscode/sourcebridge-*.vsix

Run in development mode:

cd plugins/vscode
npm install
npm run watch     # rebuilds on save
# Open the folder in VS Code, press F5 → "Run Extension"

Tests: make test-vscode (or npm test inside plugins/vscode/).

Configure

Two settings in settings.json:

Setting	Default	Description
sourcebridge.apiUrl	http://localhost:8080	URL of the SourceBridge API server
sourcebridge.debug	false	Verbose debug output in the SourceBridge output channel

The legacy sourcebridge.token setting (0.1.x) has been removed. Tokens are stored in VS Code's secret storage. If you have a value in your settings.json, the extension migrates it on first run.

Sign in

Cmd+Shift+P → SourceBridge: Sign In

Choose:

• Local password — enter email and password
• OIDC — browser redirect to your identity provider

The status bar (bottom-left) reflects connection state:

• connected · <repo> — authenticated, repo matched
• offline · retry in Ns — server unreachable, backing off
• sign in required — no valid token
• no repo — workspace has no matching indexed repo

Click the status bar item for quick actions: retry, sign in, switch repository, open logs.

Keyboard shortcuts

Shortcut	Action
Cmd+I (selection)	Open streaming AI chat for the selected code
Cmd+. (symbol)	Code-action lightbulb: link, create, show linked requirements
Cmd+K N	Generate a field guide (cliff notes) for the active file
Cmd+Shift+;	Scoped command palette — shows only actions valid for current focus

Features

Streaming AI chat

Cmd+I on any selection opens a chat panel. Tokens stream in live via the MCP streaming path. Answers carry (path:start-end) citations; clicking a citation opens the referenced file at that line range.

CodeLens, hover, and gutter decorations

Functions, methods, and classes with linked requirements show:

• Inline CodeLens above the definition: requirement title and confidence
• Hover card with requirement detail and acceptance criteria
• Gutter icon for quick navigation to the requirement detail panel

Code-action lightbulbs

Cmd+. on any symbol opens:

• Show linked requirements — opens the requirements detail panel
• Link to requirement — picker to attach an existing requirement
• Create requirement from this symbol — inline flow, pre-fills title from the symbol name, links automatically
• Ask about this symbol — shortcut to the streaming chat with the symbol as context

Requirement sidebar

Activity bar panel listing all requirements for the current repo. Features:

• Grouped by priority with inline edit / delete actions
• Substring filter
• Click any row to open the detail panel
• "Create Requirement" empty-state row when the repo has none
• All deletes are soft-deletes (30-day recycle bin)

Change Risk sidebar

Activity bar panel showing the latest impact report:

• Changed files since the last index
• Affected requirements
• Stale field guides

Click any row to open the file or requirement.

Field guide generation

Cmd+K N generates cliff notes for the active file. The sidebar also supports generating learning paths, code tours, and architecture diagrams with a lens picker (audience × depth).

Repository matching

The extension automatically matches your workspace folder to an indexed repository. Multi-root workspaces are supported — each root folder maps to a separate repo.

Auto-reconnect

The extension maintains a 30-second heartbeat when connected. When the server is unreachable, it backs off: 5 s → 15 s → 45 s → 2 min → 5 min. A window reload is not required to reconnect.

Commands

All commands are discoverable from Cmd+Shift+P with the prefix SourceBridge:

Command	Description
Configure Server	Set the API URL
Sign In / Sign Out	Local password or OIDC flow
Switch Repository	Pick which indexed repo this workspace maps to
Discuss This Code	Ask a question about the selection
Show Requirements	List requirements for the current repo
Show Linked Requirements	Requirements tied to the symbol at cursor
Generate Field Guide	Generate cliff notes for the repo, file, or symbol
Show Change Risk	Latest impact report
Show Logs	Open the output channel for troubleshooting

Troubleshooting

offline · retry in … on the status bar: The extension cannot reach the server. Check that sourcebridge.apiUrl matches the running server URL. Click the status bar → Retry now to force a probe.

No lenses / commands show as disabled: Open SourceBridge: Show Logs (Output channel). Common causes: wrong apiUrl, unindexed repo, stale auth token. Run Sign In again.

Slow LLM operations: LLM-heavy calls (Explain, Generate Field Guide) go through streaming endpoints and are not subject to the 10-second network timeout. If they stall, check the server logs and the worker connection.