VS Code Extension Architecture

The VS Code extension (packages/kilo-vscode/) is a client of Kilo CLI runtime. It bundles platform CLI binary, starts one shared editor-owned kilo serve server on demand, and drives that server through generated SDK HTTP calls plus global SSE.

Shared server ownership

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

Activation creates one KiloConnectionService. 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 kilo daemon.

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

  server["bin/kilo serve --port 0"]
  runtime["Kilo CLI 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()
  -> KiloProvider host handler
  -> generated SDK HTTP request
  -> CLI runtime
  -> /global/event SSE
  -> SdkSSEAdapter
  -> KiloConnectionService subscribers
  -> KiloProvider 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 -> CLI directory-routing middleware -> InstanceStore directory key

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

State boundaries

Directory-keyed CLI state is isolated by worktree path. Process-owned state remains shared because all Agent Manager sessions use one CLI 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 kilo:password> query mode because browser WebSocket API cannot attach Basic header. Webview CSP permits loopback HTTP and WebSocket origins for active server port. CLI also exposes scope-bound short-lived PTY ticket API as alternate browser WebSocket auth mode.

Config split

Extension-specific behavior belongs in VS Code settings. Agent runtime behavior belongs in CLI config so TUI, Console, VS Code, and JetBrains can share it.

Bundled resources

Speech-to-text captures audio locally, then sends completed recording through shared editor-owned kilo serve server to authenticated Kilo Gateway transcription path. It is batch transcription, not direct provider streaming.

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/kilo-vscode/ after changing this area.

Source map

Paths below are relative to Kilo-Org/kilocode.

Related pages

• Architecture Overview - local and hosted execution map
• CLI Runtime - shared local-server, routing, persistence, and SSE behavior
• JetBrains Plugin - corresponding editor-client architecture for JetBrains
• Development Patterns - choose code-ownership seam and validation workflow before editing extension contracts