MoonshotAI Node SDK Examples: 7 Practical Patterns for Kimi-Code Automation

The @moonshot-ai/kimi-code-sdk provides TypeScript bindings to programmatically control Kimi-Code through harness creation, configuration management, plugin operations, and session handling.

The Node SDK is the official TypeScript façade for driving Kimi-Code programmatically. It wraps the v1 and v2 engine cores (agent-core) and exposes a thin, stable RPC surface via SDKRpcClient and SDKRpcClientV2. Whether you're building CI/CD integrations, custom IDEs, or automated testing pipelines, these Node SDK examples demonstrate every major capability using real code from the repository's test suite.

Creating a Kimi Harness: V1 vs V2 API

The harness is your entry point to the SDK. It establishes an in-process client that communicates with the Kimi-Code engine.

V1 Engine (Legacy)

import { createKimiHarness } from '#/index';

const harnessV1 = createKimiHarness({
  homeDir: '/tmp/kimi-sdk-home-v1',
  identity: TEST_IDENTITY,  // test identity from the suite
});

V2 Engine (Recommended)

import { createKimiHarnessV2 } from '#/index';

const harnessV2 = createKimiHarnessV2({
  homeDir: '/tmp/kimi-sdk-home-v2',
  identity: TEST_IDENTITY,
});

Source: packages/node-sdk/test/v1-v2-parity.test.ts, lines 3–6

The v2 harness is recommended for new code. Both versions share the same method signatures for configuration, plugins, and sessions—the differences lie in the underlying engine implementation.

Configuration API Examples: Reading and Writing Config

The SDK exposes getConfig and setConfig methods that interact with Kimi-Code's config.toml.

Reading Current Configuration

// Empty home directory returns default configuration
const cfg = await harnessV1.getConfig();

Writing Configuration Patches

await harnessV2.setConfig({
  defaultModel: 'second-model',
  experimental: { 'new-flag': false },
  yolo: true,
});

// Verify persistence
const updated = await harnessV2.getConfig();

Source: packages/node-sdk/test/v1-v2-parity.test.ts, lines 39–57

The setConfig method performs a patch merge—it updates only the specified keys without overwriting the entire configuration file. Validation errors are surfaced through getConfigDiagnostics.

Plugin Management Examples

The Plugin API supports full lifecycle management: installation, listing, inspection, and enablement toggles.

Installing and Listing Plugins

// Install from a local source directory
await sdk.installPlugin('/tmp/kimi-sdk-plugin-src');

// Enumerate installed plugins
const plugins = await sdk.listPlugins();
console.log(plugins[0].displayName);  // "Parity Plugin"

// Retrieve detailed metadata (paths/timestamps scrubbed)
const info = await sdk.getPluginInfo('parity-plugin');

Source: packages/node-sdk/test/v1-v2-parity.test.ts, lines 36–44

Enabling and Disabling Plugins

// Disable entire plugin
await sdk.setPluginEnabled('parity-plugin', false);

// Disable specific MCP server within plugin
await sdk.setPluginMcpServerEnabled(
  'parity-plugin',
  'parity-stdio',    // server name from manifest
  false,
);

Source: packages/node-sdk/test/v1-v2-parity.test.ts, lines 94–109

The MCP server granularity allows fine-grained control over which Model Context Protocol endpoints remain active without uninstalling the plugin entirely.

Session API Examples: Creating and Interacting with Sessions

Sessions represent isolated conversation contexts with full history, tool call tracking, and plugin command exposure.

Creating a New Session

const session = await sdk.createSession({
  workDir: '/tmp/kimi-sdk-work',
  permission: 'yolo',    // optional permission mode
});

Retrieving Session Context

const ctx = await sdk.getContext({ sessionId: session.id });
console.log(ctx.history);  // turn-by-turn message history

Listing Plugin Commands for a Session

const commands = await sdk.listPluginCommands({ sessionId: session.id });
console.log(commands[0].name);  // "parity-command"

Source: packages/node-sdk/test/v1-v2-parity.test.ts, lines 70–88

The getContext method returns the complete conversation state including tool calls, tool results, and metadata—enabling full session reconstruction or auditing.

Session Export Example: Backup and Portability

Sessions can be exported to ZIP archives for sharing, backup, or migration between environments.

const exportResult = await sdk.exportSession({
  sessionId: session.id,
  zipPath: '/tmp/session-export.zip',
});

console.log(exportResult.manifest.version);  // bundle version

Source: packages/node-sdk/test/v1-v2-parity.test.ts, lines 124–133

The exported bundle includes the session manifest, conversation history, and any associated state required for deterministic replay on another Kimi-Code installation.

Experimental Features Example: Feature Flag Inspection

Query engine-wide experimental toggles to conditionally enable functionality:

const flags = await harnessV1.getExperimentalFeatures();
console.log(flags.map(f => f.id));  // ["flag-1", "flag-2", ...]

Source: packages/node-sdk/test/v1-v2-parity.test.ts, lines 44–48

Feature flags are read-only via the SDK—modification requires configuration changes through setConfig with the experimental key.

SDK Architecture and Key Source Files

File	Purpose
packages/node-sdk/test/v1-v2-parity.test.ts	Comprehensive example suite demonstrating every public API method
packages/node-sdk/tsconfig.api-extractor.json	Generates the public #/index export surface
packages/node-sdk/tsconfig.dts.json	Controls .d.ts declaration file emission
packages/node-sdk/vitest.config.ts	Test runner configuration ensuring CI-validated behavior

All methods described above are type-checked by the SDK's TypeScript definitions and continuously tested against both v1 and v2 engine implementations.

Summary

• Create harnesses with createKimiHarness (v1) or createKimiHarnessV2 (v2 recommended) to initialize the SDK
• Manage configuration through atomic getConfig / setConfig operations with patch semantics
• Control plugins via install, list, enable/disable, and per-MCP-server toggles
• Operate sessions with create, context retrieval, plugin command listing, and ZIP export
• Inspect flags using getExperimentalFeatures for runtime capability detection
• Reference v1-v2-parity.test.ts as living documentation for all Node SDK examples

Frequently Asked Questions

Where are the official Node SDK examples located?

The canonical examples live in packages/node-sdk/test/v1-v2-parity.test.ts within the MoonshotAI/kimi-code repository. This file serves dual purpose: it validates v1/v2 API parity in CI and demonstrates every public SDK method with runnable TypeScript code.

Should I use createKimiHarness or createKimiHarnessV2?

Use createKimiHarnessV2 for new projects. The v2 harness targets the modern engine architecture while maintaining identical method signatures for configuration, plugins, and sessions. The v1 harness remains available for legacy compatibility.

How does setConfig handle partial updates?

The setConfig method performs shallow merging—only the top-level keys you specify are overwritten, nested objects are replaced entirely. This allows targeted updates like changing defaultModel without affecting other configuration sections.

Can I modify experimental feature flags through the SDK?

No—getExperimentalFeatures is read-only. To enable or disable experimental features, use setConfig with an experimental object containing your flag toggles, then restart the harness for changes to take effect.

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