Embedded Runtime Architecture

BIGGI ships one client: the VS Code extension. The extension bundles a platform-specific local runtime from packages/opencode/ and starts it when a feature first needs a connection.

The runtime owns:

• agent execution and tool calls
• sessions, messages, permissions, and snapshots
• model-provider connections
• workspace and worktree routing
• local persistence
• the HTTP and SSE API used by the extension

BIGGI does not distribute this runtime as a standalone product. Internal package names, executable names, and source paths retain some CLI terminology to minimize conflicts while merging upstream OpenCode.

Process lifecycle

One BiggiConnectionService is created for each VS Code extension host. It lazily starts the bundled runtime with an ephemeral port, generates a random password, and connects through the generated JavaScript SDK.

The same process serves the sidebar, BIGGI editor tabs, autocomplete, and Agent Manager. If the process exits, the connection service can start a replacement.

flowchart LR
  vscode["VS Code extension"]
  service["BiggiConnectionService"]
  runtime["Bundled local runtime"]
  api["HTTP + SSE API"]
  state["Sessions and local state"]
  providers["Model providers"]

  vscode --> service
  service --> runtime
  runtime --> api
  api --> service
  runtime --> state
  runtime --> providers

Workspace routing

Agent Manager can create multiple git worktrees while reusing the extension's runtime process. Requests include a directory context, and runtime instances are keyed by normalized directory.

Some services are process-wide rather than directory-specific. When adding state, decide explicitly whether it belongs to one directory, one session, or the whole extension-host process.

Authentication

The extension passes a random runtime password through BIGGI_SERVER_PASSWORD. SDK requests use HTTP Basic authentication over loopback.

Provider credentials and remote MCP OAuth tokens are stored by the local runtime. The extension initiates those flows but does not duplicate credential storage.

SDK contract

Server route changes flow through generated and handwritten layers:

1. Define the route under packages/opencode/src/server/
2. Implement the route handler
3. Run ./script/generate.ts from the repository root
4. Commit the generated SDK and OpenAPI changes
5. Update the extension client or service that consumes the route

Do not edit generated files under packages/sdk/js/src/gen/ by hand.

Packaging

The release workflow compiles the runtime for each VS Code target, validates that each binary starts on its target platform, and passes the binaries directly to the extension packaging job.

Runtime binaries are private build artifacts. Only the resulting VSIX packages are published.

Source map

Related architecture

• VS Code Extension
• Runtime Config Schema
• Development Patterns