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

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 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)
Bridge (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)
Runtime (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)
Event Adapter (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)
Session Runtime (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)
Settings Store (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)
Packaging (vsix-package.mjs)	Builds the distributable VSIX bundle for marketplace or sideload installation.	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):

# 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:

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:

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

Settings are persisted via 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 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

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

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

// .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, 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	Extension manifest with command contributions and activation events	View on GitHub
apps/vscode/src/runtime/kimi-runtime.ts	Core runtime bootstrapping the SDK client	View on GitHub
apps/vscode/src/runtime/event-adapter.ts	Workspace event translation layer	View on GitHub
apps/vscode/src/runtime/session-runtime.ts	Session lifecycle and persistence	View on GitHub
apps/vscode/webview-ui/src/services/bridge.ts	UI-to-host RPC communication	View on GitHub
apps/vscode/webview-ui/src/main.tsx	React entry point for the chat interface	View on GitHub
apps/vscode/scripts/vsix-package.mjs	VSIX build and packaging automation	View on GitHub
apps/vscode/README.md	Official setup and troubleshooting docs	View on GitHub

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 handles SDK initialization
• Leverage IDE events automatically through 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 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 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 for the complete capabilities and activationEvents declarations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}