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

> Explore 7 practical MoonshotAI Node SDK examples to automate Kimi-Code. Harness SDK features for seamless integration and control. Get started with node-sdk today.

- Repository: [Moonshot AI/kimi-code](https://github.com/MoonshotAI/kimi-code)
- Tags: examples
- Published: 2026-08-14

---

**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)

```typescript
import { createKimiHarness } from '#/index';

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

```

### V2 Engine (Recommended)

```typescript
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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/config.toml).

### Reading Current Configuration

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

```

### Writing Configuration Patches

```typescript
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`](https://github.com/MoonshotAI/kimi-code/blob/main/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

```typescript
// 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`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/node-sdk/test/v1-v2-parity.test.ts), lines 36–44

### Enabling and Disabling Plugins

```typescript
// 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`](https://github.com/MoonshotAI/kimi-code/blob/main/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

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

```

### Retrieving Session Context

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

```

### Listing Plugin Commands for a Session

```typescript
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`](https://github.com/MoonshotAI/kimi-code/blob/main/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.

```typescript
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`](https://github.com/MoonshotAI/kimi-code/blob/main/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:

```typescript
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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/node-sdk/test/v1-v2-parity.test.ts) | Comprehensive example suite demonstrating every public API method |
| [`packages/node-sdk/tsconfig.api-extractor.json`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/node-sdk/tsconfig.api-extractor.json) | Generates the public `#/index` export surface |
| [`packages/node-sdk/tsconfig.dts.json`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/node-sdk/tsconfig.dts.json) | Controls [`.d.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/.d.ts) declaration file emission |
| [`packages/node-sdk/vitest.config.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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.