VS Code Extension Architecture

The VS Code extension (packages/biggi-vscode/) is the BIGGI client. It bundles the local runtime, starts one shared editor-owned server on demand, and drives that server through generated SDK HTTP calls plus global SSE.

Shared server ownership

Embedded Runtime defines local-server authentication, directory routing, provider routing, persistence, and SSE contracts. This page starts at the VS Code client boundary.

Activation creates one BiggiConnectionService. It owns one ServerManager, one active SDK client, and one SSE adapter. ServerManager owns child process lifecycle. This editor-owned child is separate from detached local daemon managed by biggi daemon.

flowchart LR
  subgraph host ["VS Code extension host"]
    consumers["Sidebar, tabs, panels, services"]
    service["BiggiConnectionService"]
    manager["ServerManager"]
    sdk["Generated SDK client"]
    sse["SdkSSEAdapter"]
  end

  server["bin/biggi serve --port 0"]
  runtime["BIGGI local runtime"]

  consumers --> service
  service --> manager --> server
  service --> sdk --> server
  service --> sse -->|/global/event| server
  server --> runtime

Shared consumers

Shared service has more consumers than chat tabs:

New mutable state must account for concurrent consumers and multiple directory contexts on one process.

Webview bridge

Main chat webviews use host-mediated message bridge:

webview vscode.postMessage()
  -> BiggiProvider host handler
  -> generated SDK HTTP request
  -> embedded runtime
  -> /global/event SSE
  -> SdkSSEAdapter
  -> BiggiConnectionService subscribers
  -> BiggiProvider directory/session filtering and stream coalescing
  -> webview postMessage()

Global SSE carries wrapped events for multiple directories. Connection service broadcasts incoming payload plus directory to subscribers. Providers resolve session scope, maintain message-to-session lookup where events omit direct session ID, filter for relevant views, and coalesce high-frequency stream updates before posting UI messages.

Agent Manager

Agent Manager is extension feature, not separate product. It opens as editor tab and manages parallel sessions, optional worktrees, terminals, diffs, setup scripts, and extra editor windows.

Agent Manager request path is:

session worktree path -> SDK directory -> runtime directory-routing middleware -> InstanceStore directory key

Agent Manager persists state in .biggi/agent-manager.json and worktrees under .biggi/worktrees/. Startup migration moves Agent Manager-owned data from legacy .biggi/ paths when target items do not already exist and repairs git worktree refs.

State boundaries

Directory-keyed runtime state is isolated by worktree path. Process-owned state remains shared because all Agent Manager sessions use one runtime process. Snapshot implementation state is directory-keyed, but slow-snapshot prompt guard belongs to shared Snapshot.Service scope. Managed Agent Manager prompts pass snapshotInitialization: "wait" so slow baseline setup waits without interrupting concurrently started sessions.

Terminal surfaces

VS Code extension has two terminal paths:

Agent Manager PTY WebSocket URL uses auth_token=<base64 biggi:password> query mode because browser WebSocket API cannot attach Basic header. Webview CSP permits loopback HTTP and WebSocket origins for the active server port. The runtime also exposes a scope-bound, short-lived PTY ticket API as an alternate browser WebSocket auth mode.

Config split

Extension-specific behavior belongs in VS Code settings. Agent runtime behavior belongs in runtime config.

Bundled resources

Speech-to-text and the hosted BIGGI Marketplace are not part of the current user-facing product. Do not document dormant implementation paths as available features without first shipping and enabling their complete user flow.

Recovery

Builds

Extension host bundle targets Node/CommonJS. Browser webviews and shared worker use esbuild browser bundles. Run bun run typecheck, bun run lint, and targeted unit tests from packages/biggi-vscode/ after changing this area.

Source map

Paths below are relative to stemcat/biggi.

Related pages

• Architecture Overview - local and hosted execution map
• Embedded Runtime - shared local-server, routing, persistence, and SSE behavior
• Development Patterns - choose code-ownership seam and validation workflow before editing extension contracts