CLI Runtime Architecture

The CLI (packages/opencode/) is Kilo Code's local agent engine. It owns agent execution, tools, sessions, provider integration, configuration, local persistence, directory routing, and HTTP surfaces used by editor clients and Kilo Console.

Concepts

These terms describe local execution. They are separate from hosted Cloud Agent sessions described in Cloud Platform.

One kilo serve process can host several local runtime instances. Directory-keyed state stays isolated. Process-shared service state does not.

Command entry points

flowchart LR
  run["kilo run"]
  tui["kilo TUI"]
  daemon["Detached daemon: kilo serve"]
  worker["Bun worker"]
  rpc["RPC-backed fetch and global events"]
  embedded["Embedded Server.Default().app.fetch"]
  serve["Explicit kilo serve"]
  editors["VS Code or JetBrains"]
  editorServer["Editor-owned kilo serve --port 0"]
  runtime["Kilo CLI runtime"]

  run -->|"default first choice"| daemon
  run -->|"fallback"| embedded
  run -->|"--attach"| serve
  tui -->|"default when available"| daemon
  tui -->|"fallback"| worker --> rpc --> embedded
  editors --> editorServer
  daemon --> runtime
  embedded --> runtime
  serve --> runtime
  editorServer --> runtime

TUI fallback is not direct call from UI thread to embedded fetch. UI thread starts worker.ts; worker RPC method constructs request, calls Server.Default().app.fetch(), and forwards global events back to UI thread.

One server with multiple directory contexts

Each running editor host starts one editor-owned kilo serve server. That server can handle coding sessions for workspace root and additional worktree directories at same time. It does not start separate server process for each directory.

flowchart LR
  views["Editor views<br/>Workspace root and worktrees"]
  server["One editor-owned<br/>kilo serve server"]
  store["InstanceStore"]
  root["Workspace-root<br/>local runtime instance"]
  worktree["Worktree<br/>local runtime instance"]
  sse["One process-wide<br/>/global/event stream"]

  views -->|"request includes directory"| server
  server --> store
  store -->|"select by directory"| root
  store -->|"select by directory"| worktree
  root -->|"event includes directory metadata"| sse
  worktree -->|"event includes directory metadata"| sse
  sse -->|"client routes event to matching view"| views

This distinction matters for Agent Manager worktrees and JetBrains workspace caches. Directory-keyed state stays isolated. Process-wide event stream and server-owned service state remain shared; snapshot slow-track guard is one example. Authentication, provider routing, SSE, and snapshots appear in later sections.

Authentication boundaries

Three credential boundaries coexist. Keep them separate when tracing request path or changing authentication code.

Local kilo serve access

Server Basic Auth is optional. It becomes required when KILO_SERVER_PASSWORD is non-empty. Default username is kilo; KILO_SERVER_USERNAME can override it.

PTY connect supports two browser-oriented modes: loopback query credential mode (auth_token) used by current Console and VS Code Agent Manager paths, and short-lived ticket mode exposed by server API.

Outbound provider authentication

Provider auth records use api, oauth, or wellknown variants in ${Global.Path.data}/auth.json, written with mode 0600. KILO_AUTH_CONTENT can supply process-local auth JSON. Separate v2 multi-account auth store also exists for account-oriented flows.

Remote MCP OAuth

Remote MCP OAuth belongs to CLI runtime. Static headers remain supported. For OAuth servers, CLI handles browser authorization and stores credentials in protected local state; editor clients invoke CLI-owned flow instead of storing MCP credentials themselves.

Directory routing and local runtime instances

Instance routes select directory context in this order:

1. directory query parameter.
2. x-kilo-directory request header.
3. Server process cwd.

Local routing workspace selection is separate. Session workspace, workspace query parameter, and KILO_WORKSPACE_ID can select workspace context. Configured KILO_WORKSPACE_ID keeps requests local to current workspace runtime. Other selected workspaces resolve through workspace-routing adapter to local directory or remote target.

Remote HTTP proxy responses can include sync fence metadata. Router waits for matching sync progress before returning. InstanceStore normalizes directory keys, deduplicates concurrent boots with deferred entry, and disposes directory state through registered cleanup hooks.

Core subsystems

Daemon lifecycle

kilo daemon start|status|stop|restart manage detached local kilo serve child. kilo console calls same start path, so it reuses healthy daemon instead of spawning second process.

Daemon credentials differ from editor-spawned server credentials. Current daemon source stores username kilo, password kilo, and base64 Basic token in daemon.json. File permissions protect this local credential record. Editor clients generate random passwords per spawned server.

Persistence

SQLite is default structured store.

Some JSON-backed storage remains. Session diffs still use storage path session_diff, and configuration, auth, and selected local state files retain their own owners. Snapshot storage is separate from SQLite and JSON storage.

Snapshot state boundary

Snapshot baselines use separate git directory per project worktree:

${Global.Path.data}/snapshot/<project-id>/<worktree-hash>

Snapshot implementation state is directory-keyed through InstanceState. One Snapshot.Service also owns process-shared slow-snapshot guard state outside directory cache. This distinction matters when multiple Agent Manager worktrees use same kilo serve process.

Slow initial tracking has guarded behavior:

SDK contract

CLI server contract flows through generated and handwritten layers:

1. Effect HttpApi groups under packages/opencode/src/server/routes/instance/httpapi/ define routes.
2. packages/opencode/src/server/routes/instance/httpapi/public.ts normalizes public OpenAPI to legacy-compatible request and response shapes.
3. Kilo-specific API groups and handlers live under packages/opencode/src/kilocode/server/httpapi/ and enter shared API through narrow injection seams.
4. packages/sdk/js/script/build.ts generates TypeScript v2 client from CLI OpenAPI.
5. packages/sdk/js/src/v2/client.ts adds createKiloClient() wrapper for directory and workspace routing, Electron and Node fetch compatibility, and clearer empty-response errors.
6. Root ./script/generate.ts runs SDK generation, emits tracked OpenAPI artifact, updates CLI docs, and formats outputs.
7. JetBrains Gradle build generates build-local OpenAPI, normalizes it, and generates Kotlin OkHttp client.

Regenerate checked-in JavaScript SDK output after server endpoint changes. Do not hand-edit generated client files.

Config precedence

Later sources override earlier values during instance config load:

Global config files load from ${Global.Path.config}. Project updates prefer existing config files found in ancestor .kilo, .kilocode, or .opencode directories, then existing project root config files, then create .kilo/kilo.json. Global indexing settings can carry provider and storage defaults, but global indexing.enabled is stripped so project enablement remains local in effective instance config.

Signed-in organization modes become normal agent configuration during load. They override migrated legacy modes and remain overridable by later config sources in table.

Runtime config loading is separate from editor-facing JSON Schema publication. Cloud-served schema improves validation and completion for kilo.json and kilo.jsonc; it does not load, apply, or override effective runtime config. When adding or changing config key, follow CLI Config Schema so CLI source and cloud overlay stay aligned.

Global and instance SSE

Both streams send initial server.connected event and heartbeat every 10 seconds. VS Code and JetBrains consume /global/event so one server connection can route events for multiple directories.

Kilo Console

kilo console starts or reuses daemon, opens /console, and prints Console launch URL. Browser launch URL embeds daemon Basic credentials so initial request authenticates.

Source development can serve built Console assets from package output or build them on demand. This is development behavior, not production deployment claim.

Codebase indexing

packages/kilo-indexing/ owns indexing engine. CLI bridge injects indexing plugin by default unless default plugins are disabled, then starts indexing asynchronously per normalized directory during instance bootstrap.

Source map

Paths below are relative to Kilo-Org/kilocode.

Related pages

• Architecture Overview - local and hosted execution map
• VS Code Extension - extension-host ownership, Agent Manager, and webview bridge
• JetBrains Plugin - split-mode client, bundled server lifecycle, and workspace cache
• Development Patterns - API generation, code-ownership seams, and fork-maintenance rules
• CLI Config Schema - editor validation contract for CLI config keys