# How to Integrate Kimi-Code with Your IDE: The Complete VS Code Setup Guide

> Seamlessly integrate Kimi-Code with VS Code. Follow our guide to set up the extension, connect to your Kimi-Code server, and unlock AI-assisted coding in your IDE.

- Repository: [Moonshot AI/kimi-code](https://github.com/MoonshotAI/kimi-code)
- Tags: how-to-guide
- Published: 2026-08-11

---

**Install the Kimi-Code VS Code extension, point it at a running Kimi-Code server, and use commands like "Kimi: New Session" to start AI-assisted coding directly in your editor.**

Kimi-Code, MoonshotAI's open-source AI coding assistant, provides a first-class **VS Code extension** that embeds Kimi agents into your development workflow. This guide walks through the complete integration process—from installation to advanced SDK usage—based on the actual source code in the [MoonshotAI/kimi-code](https://github.com/MoonshotAI/kimi-code) repository.

## How the Kimi-Code VS Code Extension Works

The Kimi-Code IDE integration follows a layered architecture that separates the UI from the runtime while keeping both tightly synchronized.

| Component | Role | Key Source File |
|-----------|------|-----------------|
| **VS Code extension host** | Loads the React webview UI, registers commands, and manages activation events. | [[`apps/vscode/package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vscode/package.json)](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vscode/package.json) |
| **Bridge ([`bridge.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/bridge.ts))** | JSON-RPC channel between the webview (React) and Node.js extension host using `postMessage`. | [[`apps/vscode/webview-ui/src/services/bridge.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vscode/webview-ui/src/services/bridge.ts)](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vscode/webview-ui/src/services/bridge.ts) |
| **Runtime ([`kimi-runtime.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/kimi-runtime.ts))** | Boots a `KimiClient` from the SDK, creates sessions, and streams turn data to the UI. | [[`apps/vscode/src/runtime/kimi-runtime.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vscode/src/runtime/kimi-runtime.ts)](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vscode/src/runtime/kimi-runtime.ts) |
| **Event Adapter ([`event-adapter.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/event-adapter.ts))** | Translates VS Code workspace events into agent-compatible messages for the SDK. | [[`apps/vscode/src/runtime/event-adapter.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vscode/src/runtime/event-adapter.ts)](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vscode/src/runtime/event-adapter.ts) |
| **Session Runtime ([`session-runtime.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/session-runtime.ts))** | Manages session lifecycle (create, resume, stop) and persists history to MiniDB. | [[`apps/vscode/src/runtime/session-runtime.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vscode/src/runtime/session-runtime.ts)](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vscode/src/runtime/session-runtime.ts) |
| **Settings Store ([`settings.store.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/settings.store.ts))** | Persists user configuration in VS Code's global state. | [[`apps/vscode/webview-ui/src/stores/settings.store.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vscode/webview-ui/src/stores/settings.store.ts)](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vscode/webview-ui/src/stores/settings.store.ts) |
| **Packaging (`vsix-package.mjs`)** | Builds the distributable VSIX bundle for marketplace or sideload installation. | [`apps/vscode/scripts/vsix-package.mjs`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vscode/scripts/vsix-package.mjs) |

On activation, the extension initializes the bridge, instantiates a `KimiClient` pointing at your configured server, registers commands for the command palette, subscribes to workspace events, and renders the chat panel as a side view.

## Step-by-Step: Integrate Kimi-Code with VS Code

### 1. Install the Kimi-Code Extension

**From the VS Code Marketplace:**

- Open VS Code → Extensions → Search **"Kimi-Code"** → Click **Install**

**From a local VSIX (custom builds or pre-releases):**

```bash

# Build the extension first

pnpm install
pnpm -C apps/vscode run build

# Install the produced VSIX

code --install-extension apps/vscode/dist/kimi-code-*.vsix

```

The `vsix-package.mjs` script handles bundling all webview assets, extension code, and manifests into the final installable package.

### 2. Start the Kimi-Code Server

The extension requires a running server exposing the `/api/v1` RPC surface. For local development:

```bash
pnpm -C packages/kap-server dev

# Server runs on http://localhost:3000 by default

```

For production deployments, configure your hosted URL in settings (see step 4).

### 3. Verify Activation

Open the **Output** panel (Ctrl+Shift+U) → Select **"Kimi-Code"** channel. You should see:

```

[INFO] Kimi-Code extension activated
[INFO] Bridge initialized
[INFO] Runtime connected to ws://localhost:3000

```

If you need verbose debugging, set `KIMI_CODE_EXPERIMENTAL_DEBUG=true` in your environment.

### 4. Configure Connection Settings

Open **Settings → Extensions → Kimi-Code** or edit [`.vscode/settings.json`](https://github.com/MoonshotAI/kimi-code/blob/main/.vscode/settings.json):

```json
{
  "kimiCode.serverUrl": "http://localhost:3000",
  "kimiCode.defaultModel": "kimi-k2-0711-long-context",
  "kimiCode.experimental.enableReplay": true
}

```

Settings are persisted via [`settings.store.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/settings.store.ts) and reloaded on extension restart.

### 5. Create Your First Session

- Press **Ctrl+Shift+P** → Type **"Kimi: New Session"**
- Select your model and optionally name the session
- The chat panel opens on the right—start typing prompts immediately

### 6. Leverage Automatic IDE Events

The event adapter automatically forwards these to your active agent:

- **File open/close** → `workspace/fileOpen` events
- **File save** → `workspace/fileSave` with content snapshot
- **Selection changes** → `workspace/selection` with line/column offsets

No manual configuration needed—these fire through [`event-adapter.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/event-adapter.ts) as you work.

## Advanced Integration: Using the SDK Directly

For custom extensions or tooling, import `@moonshot-ai/kimi-code-sdk` directly:

### From Another VS Code Extension

```typescript
import { KimiClient } from '@moonshot-ai/kimi-code-sdk';
import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
  const client = new KimiClient({ serverUrl: 'http://localhost:3000' });

  context.subscriptions.push(
    vscode.commands.registerCommand('myExtension.askKimi', async () => {
      const editor = vscode.window.activeTextEditor;
      const selectedCode = editor?.document.getText(editor.selection) ?? '';
      
      const response = await client.sendTurn({
        role: 'user',
        content: `Explain this code:\n\`\`\`\n${selectedCode}\n\`\`\``,
      });
      
      vscode.window.showInformationMessage(
        response?.content?.slice(0, 100) + '...' ?? 'No response'
      );
    })
  );
}

```

### React to Workspace Events Programmatically

```typescript
import { workspace, TextDocument } from 'vscode';
import { KimiClient } from '@moonshot-ai/kimi-code-sdk';

const client = new KimiClient({ serverUrl: 'http://localhost:3000' });

workspace.onDidSaveTextDocument(async (doc: TextDocument) => {
  // Only trigger for TypeScript files
  if (doc.languageId !== 'typescript') return;
  
  await client.sendTurn({
    role: 'system',
    content: `TypeScript file saved: ${doc.uri.fsPath}\n\n${doc.getText()}`,
  });
});

```

### Remote Server Configuration

```json
// .vscode/settings.json for team-shared config
{
  "kimiCode.serverUrl": "https://kimi-code.internal.company.com",
  "kimiCode.defaultModel": "kimi-k2-0711-long-context",
  "kimiCode.authToken": "${env:KIMI_API_TOKEN}"
}

```

## Session Management and Replay

Sessions persist automatically in the embedded MiniDB (`packages/minidb`). To resume work:

- **Ctrl+Shift+P** → **"Kimi: Replay"** → Select a previous session
- The full transcript loads; you can step through turns or continue the conversation

Session state is managed by [`session-runtime.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/session-runtime.ts), which handles:
- Creating new sessions with unique IDs
- Resuming from persisted history
- Graceful shutdown on VS Code close

## Key Source Files for IDE Integration

| File | Purpose | Direct Link |
|------|---------|-------------|
| [`apps/vscode/package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vscode/package.json) | Extension manifest with command contributions and activation events | [View on GitHub](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vscode/package.json) |
| [`apps/vscode/src/runtime/kimi-runtime.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vscode/src/runtime/kimi-runtime.ts) | Core runtime bootstrapping the SDK client | [View on GitHub](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vscode/src/runtime/kimi-runtime.ts) |
| [`apps/vscode/src/runtime/event-adapter.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vscode/src/runtime/event-adapter.ts) | Workspace event translation layer | [View on GitHub](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vscode/src/runtime/event-adapter.ts) |
| [`apps/vscode/src/runtime/session-runtime.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vscode/src/runtime/session-runtime.ts) | Session lifecycle and persistence | [View on GitHub](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vscode/src/runtime/session-runtime.ts) |
| [`apps/vscode/webview-ui/src/services/bridge.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vscode/webview-ui/src/services/bridge.ts) | UI-to-host RPC communication | [View on GitHub](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vscode/webview-ui/src/services/bridge.ts) |
| [`apps/vscode/webview-ui/src/main.tsx`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vscode/webview-ui/src/main.tsx) | React entry point for the chat interface | [View on GitHub](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vscode/webview-ui/src/main.tsx) |
| `apps/vscode/scripts/vsix-package.mjs` | VSIX build and packaging automation | [View on GitHub](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vscode/scripts/vsix-package.mjs) |
| [`apps/vscode/README.md`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vscode/README.md) | Official setup and troubleshooting docs | [View on GitHub](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vscode/README.md) |

## Troubleshooting Common Integration Issues

| Symptom | Cause | Fix |
|---------|-------|-----|
| "Cannot connect to Kimi-Code server" | Server not running or URL misconfigured | Verify `kimiCode.serverUrl` matches your `kap-server` instance |
| Extension commands missing | Activation failed | Check Output panel for errors; reload window (Ctrl+Shift+P → "Developer: Reload Window") |
| UI shows blank panel | Bridge initialization error | Enable `KIMI_CODE_EXPERIMENTAL_DEBUG=true` and check console |
| Sessions not persisting | MiniDB permissions | Ensure VS Code has write access to extension storage |

## Summary

- **Install** via marketplace or `code --install-extension` with a built VSIX from `scripts/vsix-package.mjs`
- **Configure** the server URL in settings to point at your `kap-server` instance
- **Create sessions** through the command palette; the runtime in [`kimi-runtime.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/kimi-runtime.ts) handles SDK initialization
- **Leverage IDE events** automatically through [`event-adapter.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/event-adapter.ts)—file saves, selections, and opens become agent context
- **Extend freely** using `@moonshot-ai/kimi-code-sdk` in your own VS Code extensions or scripts

## Frequently Asked Questions

### Does Kimi-Code work with editors other than VS Code?

Currently, the official Kimi-Code integration is built specifically for VS Code as a standard extension. The underlying SDK (`@moonshot-ai/kimi-code-sdk`) is platform-agnostic, so community extensions for other editors could leverage the same server protocol. The bridge architecture in [`bridge.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/bridge.ts) demonstrates how to adapt the SDK to any editor with webview capabilities.

### Can I run Kimi-Code entirely offline or self-hosted?

Yes. The extension connects to any server implementing the Kimi-Code API. Run `packages/kap-server` locally or on your infrastructure, then set `kimiCode.serverUrl` to your internal endpoint. No data leaves your network unless you configure a remote server.

### How do I update the Kimi-Code extension when new versions release?

Marketplace installations update automatically through VS Code's extension manager. For VSIX installations, rebuild with `pnpm -C apps/vscode run build` and reinstall. The [`package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/package.json) specifies version compatibility requirements that VS Code enforces on activation.

### What permissions does the Kimi-Code extension require?

The extension requests standard VS Code permissions: filesystem access for workspace files (to send content to agents), command palette registration, and webview creation. No network calls originate from the extension itself—all communication flows through your configured `kimiCode.serverUrl` via the SDK's WebSocket connection. Review [`apps/vscode/package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/vscode/package.json) for the complete `capabilities` and `activationEvents` declarations.