How to Integrate Kimi Code Into Your Project: SDK, Daemon, and ACP Setup Guide

Kimi Code integrates into any JavaScript/TypeScript project through three main approaches: as a typed SDK library for programmatic control, a self-hosted daemon for server-side automation, or an ACP client for IDE/editor connectivity.

Kimi Code is a modular, TypeScript-based AI-coding platform from MoonshotAI. Whether you're building a CLI tool, adding AI capabilities to an existing application, or creating an editor plugin, the repository provides purpose-built packages for each integration path. This guide covers every layer from basic SDK usage to advanced core service customization.

Integration Architecture Overview

Kimi Code is organized into four distinct integration layers, each with a dedicated package and entry point:

Integration Layer	Purpose	Primary Package	Key Entry Point
SDK (library)	Typed, contract-driven API for programmatic sessions	@moonshot-ai/kimi-code-sdk	createKimiHarness in packages/node-sdk/src/index.ts
ACP client	Thin wrapper for editor/IDE plugin communication	acp-adapter	acp-adapter/src/server.ts
Server (kap-server)	Self-hosted daemon with WebSocket/REST APIs	kap-server	packages/kap-server/src/start.ts
Core engine	DI × Scope agent runtime powering all packages	agent-core-v2	packages/agent-core-v2/src/app/scopes.ts

Installing and Using the SDK

Add the Package to Your Project

The fastest way to integrate Kimi Code is through the Node.js SDK. The repository uses pnpm as its preferred package manager:

pnpm add @moonshot-ai/kimi-code-sdk

Basic SDK Usage Pattern

The SDK exposes a minimal, type-safe API centered on sessions and streaming events:

import { createKimiHarness, type Session, type Event } from '@moonshot-ai/kimi-code-sdk';

// Create a harness that talks to the local Kimi Code daemon
const harness = await createKimiHarness();

// Open a new session (or reuse an existing one)
const session: Session = await harness.newSession();

// Send a prompt and receive streamed events
for await (const ev of session.ask('Explain the architecture of this repo')) {
  if (ev.type === 'assistant') console.log(ev.content);
}

This pattern is demonstrated in packages/node-sdk/examples/kimi-harness-smoke.ts lines 5-7, which serves as the official smoke test for SDK functionality.

Configuring Kimi Code Runtime Settings

Kimi Code uses a TOML configuration file that lives next to the executable or in ~/.config/kimi-code/. Create this file to select your model provider and runtime behavior:

# ~/.config/kimi-code/config.toml

[model]
provider = "managed:kimi-code"   # selects the built-in Kimi provider

model = "kimi-base"              # optional model name

The SDK reads this configuration automatically through the dependency chain: @moonshot-ai/kimi-code-sdk → @moonshot-ai/agent-core → config module. The full configuration schema is defined in packages/agent-core/src/config/schema.ts lines 70-78.

Running the Kimi Code Daemon (kap-server)

For self-hosted deployments—including CI pipelines, custom model providers, or offline usage—you'll need to run the kap-server daemon.

Development Mode

pnpm dev:server   # launches the daemon with hot reload

Production Deployment

pnpm build && node ./dist/kap-server.js

Server Endpoints

Once running, kap-server exposes:

• REST API at http://localhost:8969/api/v1 — defined in packages/kap-server/src/start.ts with the OpenAPI title Kimi Code Server API (lines 488-492)
• WebSocket at /api/v1/ws — protocol described in packages/protocol/src/asyncapi.ts with the AsyncAPI title Kimi Code WebSocket API (lines 6-12)

The daemon automatically loads plugins (skills, MCP servers, data sources) from plugins/official/ or user-specified directories.

Integrating via Agent Client Protocol (ACP)

For editor and IDE integration, Kimi Code implements the Agent Client Protocol (ACP).

CLI ACP Bridge

Start the ACP bridge from any terminal:

kimi acp

Zed Editor Configuration

Configure your editor to communicate with this bridge. For Zed, add this to your settings:

{
  "agent_servers": {
    "Kimi Code CLI": {
      "type": "custom",
      "command": "kimi",
      "args": ["acp"],
      "env": {}
    }
  }
}

This configuration snippet is documented in the repository's README.md lines 69-78. The ACP adapter implementation lives in packages/acp-adapter/src/server.ts.

Extending Kimi Code with Custom Skills and Plugins

Plugins extend Kimi Code's capabilities through JSON manifest files (*.plugin.json).

Plugin Structure

The Kimi WebBridge plugin provides a working example in plugins/official/kimi-webbridge/kimi.plugin.json lines 5-19, which describes a daemon that lets Kimi Code control a real browser.

Creating Your Own Plugin

1. Create my-plugin.plugin.json with name, description, and entry fields
2. Install via CLI: kimi plugin install path/to/my-plugin
3. Invoke plugin tools programmatically: session.runTool('my-tool-name', params)

Advanced: Direct Core Service Integration

For scenarios requiring custom model catalogs, per-session dependency injection, or deep runtime customization, import directly from @moonshot-ai/agent-core-v2:

import { ModelCatalogService } from '@moonshot-ai/agent-core-v2/src/services/model-catalog';

const catalog = new ModelCatalogService();
await catalog.addProvider({ 
  provider_id: 'my-provider', 
  // additional provider configuration 
});

The ModelCatalogService implementation is located in packages/agent-core-v2/src/services/model-catalog.service.ts.

Complete Integration Example

Here's a minimal program that reads a TypeScript file and asks Kimi Code to explain it:

// example.ts – a minimal program that explains a file
import { createKimiHarness } from '@moonshot-ai/kimi-code-sdk';
import { readFileSync } from 'fs';

async function main() {
  const harness = await createKimiHarness();
  const session = await harness.newSession();

  const source = readFileSync('src/index.ts', 'utf8');
  const prompt = `Explain what this TypeScript file does:\n\n${source}`;

  for await (const ev of session.ask(prompt)) {
    if (ev.type === 'assistant') process.stdout.write(ev.content);
  }
}

main().catch(console.error);

Run with:

pnpm ts-node example.ts

Summary

• Install the SDK with pnpm add @moonshot-ai/kimi-code-sdk for typed, programmatic access
• Configure runtime via ~/.config/kimi-code/config.toml to select models and providers
• Start kap-server (pnpm dev:server) for self-hosted REST and WebSocket APIs
• Use createKimiHarness and session.ask() to drive AI-assisted coding sessions
• Enable ACP (kimi acp) for IDE/editor integration
• Add plugins by creating JSON manifests and installing via the CLI
• Access core services from agent-core-v2 for advanced customization scenarios

Frequently Asked Questions

Do I need to run the daemon to use the SDK?

Yes—createKimiHarness() connects to a running Kimi Code daemon over local IPC or TCP. For development, run pnpm dev:server. For production, build and deploy the kap-server package. The SDK cannot operate independently because session management, model providers, and tool execution live in the daemon process.

Can I use Kimi Code with Python or other languages?

Not directly. Kimi Code is built in TypeScript and its primary SDK is Node.js-based. However, you can interact with a running kap-server via its REST API (http://localhost:8969/api/v1) or WebSocket endpoint from any language. The OpenAPI and AsyncAPI specifications in packages/kap-server/src/start.ts and packages/protocol/src/asyncapi.ts document these interfaces.

What is the difference between the SDK and ACP integration?

The SDK (@moonshot-ai/kimi-code-sdk) is a thick client library with typed contracts for building applications that embed Kimi Code. ACP is a thin, standardized protocol for editor/IDE plugins that need minimal, stateless communication with the daemon. Use the SDK for application development; use ACP when building editor extensions that must follow the Agent Client Protocol specification.

How do I add a custom model provider?

Create a custom ModelCatalogService from agent-core-v2, or add provider configuration to your config.toml under the [model] section. For dynamic provider registration at runtime, instantiate ModelCatalogService directly and call addProvider() with your provider's configuration object, as shown in packages/agent-core-v2/src/services/model-catalog.service.ts.

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