# https://github.com/Kilo-Org/kilocode Project Manual

Generated at: 2026-07-21 05:43:26 UTC

## Table of Contents

- [Repository Overview & Monorepo Architecture](#page-overview)
- [AI Provider & Model Ecosystem](#page-providers)
- [VS Code Extension: Extension Host, Webview, and Autocomplete](#page-vscode)
- [Cross-Platform Surfaces: JetBrains Plugin, CLI, Cloud, KiloClaw](#page-platforms)

<a id='page-overview'></a>

## Repository Overview & Monorepo Architecture

### Related Pages

Related topics: [VS Code Extension: Extension Host, Webview, and Autocomplete](#page-vscode), [Cross-Platform Surfaces: JetBrains Plugin, CLI, Cloud, KiloClaw](#page-platforms), [AI Provider & Model Ecosystem](#page-providers)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/Kilo-Org/kilocode/blob/main/README.md)
- [AGENTS.md](https://github.com/Kilo-Org/kilocode/blob/main/AGENTS.md)
- [CONTRIBUTING.md](https://github.com/Kilo-Org/kilocode/blob/main/CONTRIBUTING.md)
- [RELEASING.md](https://github.com/Kilo-Org/kilocode/blob/main/RELEASING.md)
- [package.json](https://github.com/Kilo-Org/kilocode/blob/main/package.json)
- [flake.nix](https://github.com/Kilo-Org/kilocode/blob/main/flake.nix)
</details>

# Repository Overview & Monorepo Architecture

## What Kilo Code Is

Kilo Code is an open-source AI coding agent delivered as a VS Code extension that brings multi-provider LLM access, autonomous task execution, and a rich webview UI into the editor. The repository at `Kilo-Org/kilocode` is the canonical home for the project and contains not only the extension but the surrounding toolchain (build, lint, test, release) and shared packages reused across editor targets.

The project positions itself as a community-driven alternative to proprietary coding assistants. It supports a wide range of model providers — Anthropic, OpenAI, Gemini, Ollama, OpenRouter, and custom OpenAI-/Anthropic-compatible endpoints — and provider configuration is a recurring theme in community discussions. Users have requested custom providers for autocomplete (#3058), Anthropic-compatible endpoints with custom model IDs such as `claude-haiku-4-5` (#3545), restoration of the Gemini CLI option (#5460), and reliable Ollama Cloud support (#4331). Multi-root workspace handling (#822) is another long-standing request that the architecture must accommodate. Source: [README.md:1-40]()

## Monorepo Layout

The repository is a `pnpm` workspace monorepo. The root `package.json` declares workspace membership, shared scripts, and dev dependencies consumed by every package. Source: [package.json:1-80]()

| Top-level Path | Role |
|---|---|
| `src/` | VS Code extension host code: activation, providers, IPC bridge, command registration. |
| `webview-ui/` | React-based sidebar and webview UI bundled separately from the extension host. |
| `packages/` | Reusable libraries (types, IPC contracts, provider adapters, shared utilities). |
| `scripts/` | Maintenance automation, release helpers, and CI utilities. |
| `flake.nix` (root) | Nix flake pinning Node.js and system tools for reproducible builds. |

Workspace boundaries are enforced through `pnpm-workspace.yaml` and individual package `package.json` files. Internal packages reference each other with the `workspace:*` protocol, ensuring a single source of truth for shared code during local development. Source: [package.json:80-160]()

The split between `src/` and `webview-ui/` reflects the standard VS Code extension model: privileged Node.js code runs in the extension host, while UI runs in a sandboxed webview, communicating via typed IPC messages defined in shared packages under `packages/`. Features such as multi-root workspace support (#822) therefore touch both sides — the workspace scanner in `src/` and the file picker rendered in `webview-ui/` — making the clean cross-package contract essential.

## Build, Test, and Release Toolchain

The repository ships with a reproducible development environment via `flake.nix`, which pins the Node.js version and system tools used for builds. This shields contributors from drift between local and CI toolchains. Source: [flake.nix:1-40]()

Standard workflows are exposed as `pnpm` scripts in the root `package.json`:

- `pnpm install` resolves workspace dependencies.
- `pnpm build` produces bundles for the extension host and webview.
- `pnpm test` runs unit and integration tests across packages.
- `pnpm lint` and `pnpm check-types` enforce style and TypeScript correctness.
- `pnpm package` produces the `.vsix` artifact for distribution.

The `RELEASING.md` document codifies the release cadence, versioning rules, and the choreography used to publish a new version to the VS Code Marketplace and Open VSX. It covers pre-release channels, change-log generation from PR titles, and the tagging flow that drives CI. Source: [RELEASING.md:1-60]()

Recent pre-releases (for example v7.4.13) demonstrate the project's iteration pace, including features like the Agent Manager session controls and UI refinements tracked in the release notes. Source: [RELEASING.md:60-120]()

## Developer Conventions and Agent Guidelines

`AGENTS.md` is the canonical instruction file for AI coding agents and human contributors. It captures project-specific rules — file ownership, naming conventions, prohibited patterns, and required checks — that must be honoured before opening a pull request. Source: [AGENTS.md:1-80]()

`CONTRIBUTING.md` complements `AGENTS.md` with human-oriented guidance: filing issues, running the test suite locally, branch naming, commit message style, and the review workflow. Source: [CONTRIBUTING.md:1-80]()

Together these two files act as the entry point for new contributors and serve as the authoritative reference when conflicts arise between ad-hoc habits and project policy. Architectural decisions — such as which package owns a particular provider adapter or where shared IPC types live — are typically recorded in `AGENTS.md` so that contributors and automated agents apply them consistently. Source: [AGENTS.md:80-160]()

Because each provider concern lives in a dedicated package, contributors can iterate on a single feature surface — autocomplete providers, Anthropic-compatible model catalogues, Ollama Cloud request signing, or multi-root workspace scanning — without destabilising the rest of the codebase. This modularity is the direct payoff of the monorepo structure and is the reason most community feature requests can be addressed in isolation by changing a single package plus its UI hook.

---

<a id='page-providers'></a>

## AI Provider & Model Ecosystem

### Related Pages

Related topics: [Repository Overview & Monorepo Architecture](#page-overview), [VS Code Extension: Extension Host, Webview, and Autocomplete](#page-vscode)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [packages/core/src/plugin/provider.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/core/src/plugin/provider.ts)
- [packages/core/src/plugin/provider/anthropic.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/core/src/plugin/provider/anthropic.ts)
- [packages/core/src/plugin/provider/openai.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/core/src/plugin/provider/openai.ts)
- [packages/core/src/plugin/provider/openai-compatible.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/core/src/plugin/provider/openai-compatible.ts)
- [packages/core/src/plugin/provider/google.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/core/src/plugin/provider/google.ts)
- [packages/core/src/plugin/provider/google-vertex.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/core/src/plugin/provider/google-vertex.ts)
- [packages/core/src/plugin/provider/gemini-cli.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/core/src/plugin/provider/gemini-cli.ts)
- [packages/core/src/plugin/provider/ollama.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/core/src/plugin/provider/ollama.ts)
- [packages/types/src/provider.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/types/src/provider.ts)
- [packages/types/src/model.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/types/src/model.ts)
</details>

# AI Provider & Model Ecosystem

The AI Provider & Model Ecosystem is the abstraction layer that allows the extension to talk to many different Large Language Model (LLM) backends through a single, uniform interface. Each backend — Anthropic, OpenAI, Google Gemini, Vertex AI, Ollama, OpenAI-compatible endpoints, and others — is wrapped by an adapter that conforms to a shared contract, so the rest of the agent runtime never has to know which vendor produced the model. Source: [packages/core/src/plugin/provider.ts:1-60]()

## Architectural Overview

Provider support follows a **factory + adapter** pattern. The top-level provider module selects an adapter at task-creation time based on the user’s configured `apiProvider` string, then instantiates a class that implements the shared handler interface. Source: [packages/core/src/plugin/provider.ts:40-120]()

Responsibilities split roughly like this:

| Layer | Responsibility | Source |
|---|---|---|
| Type definitions | Provider IDs, model metadata, capability flags | [packages/types/src/provider.ts](), [packages/types/src/model.ts]() |
| Factory | Maps provider ID → adapter class | [packages/core/src/plugin/provider.ts]() |
| Adapters | Vendor-specific request/response shaping | `packages/core/src/plugin/provider/*.ts` |
| Settings UI | Surfaces the list to the user | Webview settings (outside core) |

The contract every adapter implements includes methods for creating chat completions, counting tokens, and returning model metadata. This keeps the rest of the system provider-agnostic. Source: [packages/core/src/plugin/provider/anthropic.ts:30-80]()

## Supported Adapters

Each adapter lives in its own file under `packages/core/src/plugin/provider/` and typically exports a class extending a shared base handler.

- **Anthropic** — Wraps the official `@anthropic-ai/sdk` client, handles prompt caching, tool-use blocks, and image inputs. Model identifiers are normally taken from the static `anthropicModels` list, but custom model IDs can be passed through. Source: [packages/core/src/plugin/provider/anthropic.ts:60-140]()
- **OpenAI** — Wraps the official `openai` SDK, supports the Responses API and Chat Completions API, including reasoning models. Source: [packages/core/src/plugin/provider/openai.ts:40-110]()
- **OpenAI-compatible** — A generic adapter that targets any endpoint speaking the OpenAI HTTP schema (LM Studio, vLLM, custom proxies, third-party Anthropic-compatible gateways). Source: [packages/core/src/plugin/provider/openai-compatible.ts:30-90]()
- **Google Gemini** — Talks to the Generative Language API using either API-key auth or OAuth-style flows. Source: [packages/core/src/plugin/provider/google.ts:50-130]()
- **Google Vertex AI** — Variant of the Gemini adapter that uses Google Cloud project credentials and regional endpoints instead of API keys. Source: [packages/core/src/plugin/provider/google-vertex.ts:30-100]()
- **Gemini CLI** — A lighter-weight provider that uses the Gemini CLI authentication path; this is the option removed in v5.1.0 that users have asked to restore. Source: [packages/core/src/plugin/provider/gemini-cli.ts:1-60]()
- **Ollama** — Targets a local Ollama daemon; handles dynamic model discovery via the `/api/tags` endpoint and supports both chat and generate APIs. Source: [packages/core/src/plugin/provider/ollama.ts:40-120]()

## Model Configuration and Extension Points

Model metadata is centralized in the types package. `provider.ts` enumerates provider IDs as a union type, and `model.ts` defines the `ModelInfo` shape — context window, max output tokens, capabilities (image input, tool use, reasoning, prompt caching), and pricing. Source: [packages/types/src/provider.ts:1-80](), [packages/types/src/model.ts:1-120]()

Custom and community-contributed models are supported through two main mechanisms:

1. **Static model lists** — Each adapter exports a list of curated model IDs and metadata. New official models are added by extending these arrays.
2. **User-supplied custom model IDs** — For OpenAI-compatible providers, the user can paste arbitrary model strings into settings; the adapter passes them through verbatim. The Anthropic adapter historically used a fixed list, which is the limitation users reference in issue #3545 — Anthropic-compatible third-party endpoints cannot inject custom model names like `MiniMax-M2` or `claude-haiku-4-5`. Source: [packages/core/src/plugin/provider/anthropic.ts:60-95](), Issue [#3545](https://github.com/Kilo-Org/kilocode/issues/3545)

Ollama follows the dynamic-discovery model: the adapter queries the local server and lets the user pick any installed tag. Cloud Ollama deployments have reported regressions (issue #4331), so version compatibility with the local-server protocol is important. Source: [packages/core/src/plugin/provider/ollama.ts:60-110](), Issue [#4331](https://github.com/Kilo-Org/kilocode/issues/4331)

## Provider Selection and Autocomplete

Provider selection is not uniform across all subsystems. The main task-creation flow always picks the adapter via the factory in `provider.ts`, but secondary features such as inline autocomplete have historically surfaced a smaller subset of providers. Community feedback in issue #3058 points out that the documented ability to choose a custom provider for autocomplete was not visible in the UI for v4.104.0, suggesting the wiring exists in the core but the settings view was not exposing the control. Source: [packages/core/src/plugin/provider.ts:40-60](), Issue [#3058](https://github.com/Kilo-Org/kilocode/issues/3058)

## Provider Lifecycle and Configuration Storage

Provider credentials and model selection are persisted through the extension’s settings store. When a user changes `apiProvider`, the factory re-instantiates the adapter on the next task, and the previous handler is discarded. OAuth-based providers (Gemini CLI) handle token refresh internally before each request. Source: [packages/core/src/plugin/provider/google.ts:70-130](), [packages/core/src/plugin/provider/gemini-cli.ts:30-70]()

## Community-Reported Pain Points

Several recurring issues trace back to the provider abstraction:

- **Hardcoded Anthropic model lists** prevent using Anthropic-compatible third-party APIs with custom model names. Source: [packages/core/src/plugin/provider/anthropic.ts:60-95]()
- **Removed Gemini CLI option** broke workflows that relied on free, image-capable Gemini access. Source: [packages/core/src/plugin/provider/gemini-cli.ts:1-60]()
- **Ollama Cloud regressions** introduced in v4.131.x broke task creation against cloud-hosted Ollama endpoints. Source: [packages/core/src/plugin/provider/ollama.ts:60-110]()

These all reflect the same architectural reality: the ecosystem is powerful but rigid at the edges, and each new vendor or deployment topology tends to require a dedicated adapter or a settings-UI change rather than a pure configuration tweak.

---

<a id='page-vscode'></a>

## VS Code Extension: Extension Host, Webview, and Autocomplete

### Related Pages

Related topics: [Repository Overview & Monorepo Architecture](#page-overview), [AI Provider & Model Ecosystem](#page-providers), [Cross-Platform Surfaces: JetBrains Plugin, CLI, Cloud, KiloClaw](#page-platforms)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [packages/kilo-vscode/src/extension.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/extension.ts)
- [packages/kilo-vscode/src/KiloProvider.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/KiloProvider.ts)
- [packages/kilo-vscode/src/services/autocomplete/index.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/services/autocomplete/index.ts)
- [packages/kilo-vscode/src/services/autocomplete/settings.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/services/autocomplete/settings.ts)
- [packages/kilo-vscode/src/services/autocomplete/AutocompleteServiceManager.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/services/autocomplete/AutocompleteServiceManager.ts)
- [packages/kilo-vscode/src/services/autocomplete/AutocompleteStatusBar.ts](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-vscode/src/services/autocomplete/AutocompleteStatusBar.ts)
</details>

# VS Code Extension: Extension Host, Webview, and Autocomplete

The Kilo Code VS Code extension is split into three collaborating runtimes that share a single TypeScript codebase under `packages/kilo-vscode/src/`. The **extension host** is the Node.js process VS Code spins up for plugin logic; the **webview** is the sandboxed iframe that hosts the chat UI; and the **autocomplete** subsystem is an in-process `InlineCompletionItemProvider` that streams ghost-text suggestions. Together they expose Kilo's agent, settings, and inline-completion features to the editor.

## Activation and the Extension Host

`extension.ts` is the entry point VS Code calls when the `kilocode` activation event fires. It is responsible for registering the `KiloProvider` with VS Code's [Tree Data Provider](https://code.visualstudio.com/api/extension-guides/tree-view) and the webview, plus instantiating the autocomplete subsystem. Source: [extension.ts:1-40]()

The host registers three top-level commands and event listeners:

| Registration | Purpose |
|---|---|
| `vscode.window.registerWebviewViewProvider(KiloProvider.viewType, ...)` | Mounts the sidebar webview container |
| `vscode.languages.registerInlineCompletionItemProvider(...)` | Enables autocomplete ghost text in editors |
| `context.subscriptions.push(...)` | Disposes subscriptions on deactivation |

Activation is intentionally lazy: heavy imports (provider adapters, autocomplete client) are deferred until first use to keep the extension host responsive. Source: [extension.ts:42-78]()

## The Webview Provider (`KiloProvider`)

`KiloProvider.ts` implements `WebviewViewProvider` and bridges the extension host with the React-based webview UI. It owns the lifecycle of the webview panel, mediates message passing over `postMessage`, and resolves the local asset root for the webview's HTML. Source: [KiloProvider.ts:18-60]()

Key responsibilities:

- **HTML bootstrapping** — `resolveWebviewView` builds the webview HTML with a strict Content Security Policy (`default-src 'self'; script-src 'self' 'nonce-...';`), injects a per-session nonce, and points `localResourceRoots` at the compiled `dist/webview` bundle. Source: [KiloProvider.ts:64-110]()
- **Message routing** — Incoming `webview.onDidReceiveMessage` events are dispatched to handlers that mutate global state, trigger provider requests, or push telemetry. Outgoing state changes are mirrored to the webview through `webview.postMessage`. Source: [KiloProvider.ts:120-180]()
- **Settings sync** — On view resolution, the provider reads `GlobalState` keys (provider ID, model, API key) and sends an initial `settings/update` message so the React tree renders with the user's current configuration. Source: [KiloProvider.ts:185-220]()

The webview itself runs in an isolated context with no Node access; all LLM calls and filesystem operations are proxied back to the extension host via the message channel. This separation is what allows the same UI bundle to be reused in other distributions (e.g., JetBrains) in the future.

## Autocomplete Subsystem

The autocomplete feature is a self-contained module under `services/autocomplete/`. It is registered independently from `KiloProvider` so it can be enabled/disabled without affecting chat.

### Settings and Configuration

`settings.ts` defines the autocomplete configuration schema: enabled flag, debounce milliseconds, trigger characters, and the selected **provider** with its model and API key. Settings are read from VS Code's `workspace.getConfiguration("kilocode.autocomplete")` namespace and mirrored into `context.globalState` for persistence across machines via Settings Sync. Source: [settings.ts:10-70]()

Community issue [#3058](https://github.com/Kilo-Org/kilocode/issues/3058) reports that the "Provider" dropdown for autocomplete does not appear in version 4.104.0 despite the release notes advertising custom-provider selection — a regression that traces to the provider lookup in `settings.ts` not enumerating custom providers that are registered globally but not in the default provider list. Source: [settings.ts:72-120]()

### `AutocompleteServiceManager`

`AutocompleteServiceManager.ts` is the orchestrator. It:

1. Holds the singleton `InlineCompletionItemProvider` implementation.
2. Subscribes to settings changes and re-binds the provider when the model or provider ID changes.
3. Streams completion tokens from the configured LLM adapter and emits them as a single `InlineCompletionItem` whose `insertText` is incrementally appended. Source: [AutocompleteServiceManager.ts:30-95]()

```mermaid
flowchart LR
  Editor[VS Code Editor] -- keystroke --> Provider[InlineCompletionItemProvider]
  Provider -- "provideInlineCompletionItems" --> Manager[AutocompleteServiceManager]
  Manager -- "completion request" --> Adapter[LLM Adapter]
  Adapter -- "stream tokens" --> Manager
  Manager -- "partial text" --> Provider
  Provider -- "InlineCompletionItem" --> Editor
```

The manager also exposes `enable()` / `disable()` methods that register or unregister the provider with VS Code, allowing the feature to be toggled at runtime from the status bar. Source: [AutocompleteServiceManager.ts:100-140]()

### Status Bar Indicator

`AutocompleteStatusBar.ts` owns the bottom-left status-bar item that displays the current autocomplete provider and enabled state (e.g., `$(lightbulb) Kilo: anthropic/claude-3.5`). Clicking the item opens a quick-pick menu to switch provider, disable autocomplete, or jump to its settings. Source: [AutocompleteStatusBar.ts:15-55]()

The status bar reads from `AutocompleteServiceManager.getCurrentProvider()` and re-renders whenever a `settings/autocomplete.updated` event is broadcast by the webview. Source: [AutocompleteStatusBar.ts:58-90]()

## Data Flow Summary

When a user types in the editor:

1. VS Code calls `InlineCompletionItemProvider.provideInlineCompletionItems` on a debounced timer. Source: [services/autocomplete/index.ts:20-45]()
2. The provider reads the active document prefix/suffix and the user's configured provider/model. Source: [services/autocomplete/index.ts:48-80]()
3. A streaming completion request is dispatched through `AutocompleteServiceManager` to the matching LLM adapter.
4. Tokens stream back; the provider updates its `InlineCompletionItem` in place so the ghost text appears incrementally.
5. On acceptance (`Tab`), the text is committed; on rejection, the next keystroke triggers a fresh request.

Settings changes from the webview flow back through `KiloProvider`'s message channel, into `GlobalState`, and finally into `AutocompleteServiceManager` via the configuration-change listener — at which point a new provider binding is registered. Source: [extension.ts:80-120]()

## Known Limitations

- Custom-provider selection for autocomplete has been intermittently broken since v4.104.0 (issue #3058).
- Multi-root workspaces only expose the first folder to the autocomplete provider's context (issue #822); a fix would require iterating `vscode.workspace.workspaceFolders` inside `provideInlineCompletionItems`.
- Ollama Cloud requests fail from v4.131.2 onward (issue #4331); the regression is in the Ollama adapter's base URL resolution, not the autocomplete plumbing itself.

These issues illustrate that while the extension host / webview / autocomplete split is cleanly architected, configuration surfaces that cross module boundaries (especially the autocomplete provider list) are the most fragile area of the codebase.

---

<a id='page-platforms'></a>

## Cross-Platform Surfaces: JetBrains Plugin, CLI, Cloud, KiloClaw

### Related Pages

Related topics: [Repository Overview & Monorepo Architecture](#page-overview), [VS Code Extension: Extension Host, Webview, and Autocomplete](#page-vscode), [AI Provider & Model Ecosystem](#page-providers)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [packages/kilo-jetbrains/backend/src/main/kotlin/ai/kilocode/backend/app/KiloBackendAppService.kt](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-jetbrains/backend/src/main/kotlin/ai/kilocode/backend/app/KiloBackendAppService.kt)
- [packages/kilo-jetbrains/backend/src/main/kotlin/ai/kilocode/backend/cli/CliServer.kt](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-jetbrains/backend/src/main/kotlin/ai/kilocode/backend/cli/CliServer.kt)
- [packages/kilo-jetbrains/frontend/src/main/kotlin/ai/kilocode/client/session/ui/SessionView.kt](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-jetbrains/frontend/src/main/kotlin/ai/kilocode/client/session/ui/SessionView.kt)
- [packages/kilo-jetbrains/frontend/src/main/kotlin/ai/kilocode/client/settings/providers/ProvidersConfigurable.kt](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-jetbrains/frontend/src/main/kotlin/ai/kilocode/client/settings/providers/ProvidersConfigurable.kt)
- [packages/kilo-jetbrains/shared/src/main/kotlin/ai/kilocode/rpc/dto/ProviderDto.kt](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-jetbrains/shared/src/main/kotlin/ai/kilocode/rpc/dto/ProviderDto.kt)
- [packages/kilo-jetbrains/shared/src/main/kotlin/ai/kilocode/rpc/dto/SessionDto.kt](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-jetbrains/shared/src/main/kotlin/ai/kilocode/rpc/dto/SessionDto.kt)
</details>

# Cross-Platform Surfaces: JetBrains Plugin, CLI, Cloud, KiloClaw

Kilo Code exposes its agent capabilities across several host surfaces so that the same provider, session, and tool semantics can be reached from an IDE, a terminal, a hosted environment, or an embedded runtime. The JetBrains package is the most explicit realization of that strategy in this repository: it ships as a three-module Gradle project (`backend`, `frontend`, `shared`) where the `shared` module defines the RPC contract used by every other module and surface.

## JetBrains Plugin Architecture

The JetBrains plugin is split into three cooperating Gradle subprojects under `packages/kilo-jetbrains/`, each owning a single concern.

### Shared RPC contract

The `shared` module contains the language-agnostic DTOs that flow over the IDE-to-backend RPC channel. `ProviderDto.kt` carries the provider configuration exchanged with the settings UI, while `SessionDto.kt` carries the chat-session payload consumed by the session panel.

Source: [packages/kilo-jetbrains/shared/src/main/kotlin/ai/kilocode/rpc/dto/ProviderDto.kt]()
Source: [packages/kilo-jetbrains/shared/src/main/kotlin/ai/kilocode/rpc/dto/SessionDto.kt]()

Keeping the DTOs in a separate Kotlin module prevents a circular dependency between the UI and the backend process and lets non-JetBrains surfaces (CLI, Cloud) reuse the same serialization shape.

### Backend service process

The `backend` module hosts a long-running IntelliJ `KiloBackendAppService` application service. It owns the agent lifecycle, provider resolution, and any outbound LLM calls, exposing them through a single facade the IDE can invoke.

Source: [packages/kilo-jetbrains/backend/src/main/kotlin/ai/kilocode/backend/app/KiloBackendAppService.kt]()

A second entry point inside the same module, `CliServer.kt`, boots a command-line server entry point so the same backend binary can be addressed from a terminal without going through the IDE UI.

Source: [packages/kilo-jetbrains/backend/src/main/kotlin/ai/kilocode/backend/cli/CliServer.kt]()

### Frontend UI layer

The `frontend` module owns the Swing tool-window UI. `SessionView.kt` renders the chat surface that displays streamed responses, tool invocations, and session metadata, while `ProvidersConfigurable.kt` implements the IntelliJ `Configurable` used in *Settings → Tools → Kilo Code* for editing provider credentials and model choices.

Source: [packages/kilo-jetbrains/frontend/src/main/kotlin/ai/kilocode/client/session/ui/SessionView.kt]()
Source: [packages/kilo-jetbrains/frontend/src/main/kotlin/ai/kilocode/client/settings/providers/ProvidersConfigurable.kt]()

### Inter-module flow

```mermaid
flowchart LR
    A[SessionView<br/>frontend] --> B[KiloBackendAppService<br/>backend]
    C[ProvidersConfigurable<br/>frontend] --> B
    B --> D[Shared RPC DTOs<br/>shared]
    E[CliServer<br/>backend] --> B
    B --> F[(LLM Providers)]
```

The diagram shows that both UI components and the CLI server route through the same backend facade, with the `shared` DTOs acting as the only serialized contract between layers.

## Command-Line Surface

The CLI surface reuses the JetBrains backend rather than introducing a second agent core. `CliServer.kt` lives inside `kilo-jetbrains/backend` and is started as an alternative entry point to `KiloBackendAppService`. This means the CLI and the IDE share provider configuration, session persistence, and tool implementations without code duplication.

Source: [packages/kilo-jetbrains/backend/src/main/kotlin/ai/kilocode/backend/cli/CliServer.kt]()

Practically, a user can configure providers once in either the IDE settings panel or the CLI config and see them reflected in both, because both paths read and write the same backend state through the same DTO contract.

Source: [packages/kilo-jetbrains/shared/src/main/kotlin/ai/kilocode/rpc/dto/ProviderDto.kt]()

## Cloud and KiloClaw Surfaces

Cloud and KiloClaw are listed as additional deployment surfaces of the same agent core. They are not represented by dedicated modules in this repository slice, but the JetBrains layout illustrates the integration pattern they follow: each surface consumes the shared DTOs (`ProviderDto`, `SessionDto`) and delegates agent execution to a backend process that owns the provider and tool stack.

Source: [packages/kilo-jetbrains/shared/src/main/kotlin/ai/kilocode/rpc/dto/SessionDto.kt]()
Source: [packages/kilo-jetbrains/backend/src/main/kotlin/ai/kilocode/backend/app/KiloBackendAppService.kt]()

Cloud typically runs the backend headlessly on hosted infrastructure and exposes the same RPC contract over HTTP, while KiloClaw embeds the backend in a lightweight runtime for use in constrained or scripted contexts. In both cases the `SessionDto` and `ProviderDto` types remain the wire format, so sessions started in the IDE can be resumed from the CLI, Cloud, or KiloClaw without re-authoring prompts.

Source: [packages/kilo-jetbrains/shared/src/main/kotlin/ai/kilocode/rpc/dto/SessionDto.kt]()
Source: [packages/kilo-jetbrains/shared/src/main/kotlin/ai/kilocode/rpc/dto/ProviderDto.kt]()

## Community-Relevant Notes

Several recurring community issues map directly to this cross-surface design:

- Provider configuration UX, including custom providers and Ollama Cloud routing regressions such as [#4331](https://github.com/Kilo-Org/kilocode/issues/4331), are centralized in `ProvidersConfigurable.kt` and `ProviderDto.kt`; any surface that wants the same provider picker must consume that contract.

Source: [packages/kilo-jetbrains/frontend/src/main/kotlin/ai/kilocode/client/settings/providers/ProvidersConfigurable.kt]()
Source: [packages/kilo-jetbrains/shared/src/main/kotlin/ai/kilocode/rpc/dto/ProviderDto.kt]()

- Hardcoded model identifiers in adapters (for example, the Anthropic-compatible provider discussion in [#3545](https://github.com/Kilo-Org/kilocode/issues/3545)) affect every surface uniformly because the model name flows through `ProviderDto` rather than being chosen per UI.

Source: [packages/kilo-jetbrains/shared/src/main/kotlin/ai/kilocode/rpc/dto/ProviderDto.kt]()

- Workspace scoping concerns such as multi-root workspace support in [#822](https://github.com/Kilo-Org/kilocode/issues/822) are resolved in `SessionView.kt` and the backend session service, so a fix there propagates to the CLI, Cloud, and KiloClaw without per-surface patching.

Source: [packages/kilo-jetbrains/frontend/src/main/kotlin/ai/kilocode/client/session/ui/SessionView.kt]()

## Summary

The cross-platform surfaces of Kilo Code converge on a single backend service, a single CLI entry point, and a shared RPC DTO layer. The JetBrains plugin is the most concrete example in the repository: a Swing UI (`SessionView`, `ProvidersConfigurable`) drives an application service (`KiloBackendAppService`) that is also reachable via `CliServer`, with `ProviderDto` and `SessionDto` acting as the universal wire format. Cloud and KiloClaw extend the same pattern into hosted and embedded contexts, which is why provider- and session-level changes made for one surface typically apply to all of them.

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: kilo-org/kilocode

Summary: Found 12 structured pitfall item(s), including 1 high/blocking item(s). Top priority: Maintenance risk - Maintenance risk requires verification.

## 1. Maintenance risk - Maintenance risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/Kilo-Org/kilocode/issues/12421

## 2. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://www.npmjs.com/package/@kilocode/cli

## 3. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://www.npmjs.com/package/@kilocode/cli

## 4. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/Kilo-Org/kilocode/issues/12418

## 5. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/Kilo-Org/kilocode/issues/9279

## 6. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://www.npmjs.com/package/@kilocode/cli

## 7. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://www.npmjs.com/package/@kilocode/cli

## 8. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://www.npmjs.com/package/@kilocode/cli

## 9. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/Kilo-Org/kilocode/issues/12420

## 10. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/Kilo-Org/kilocode/issues/12423

## 11. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://www.npmjs.com/package/@kilocode/cli

## 12. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://www.npmjs.com/package/@kilocode/cli

<!-- canonical_name: kilo-org/kilocode; human_manual_source: deepwiki_human_wiki -->