# How to Integrate with the `klient` Package from Kimi-Code: A Complete Guide

> Integrate with the @moonshot-ai/klient package from Kimi-Code using memory or IPC transport. Access typed facades for global, session, and agent operations. Connect to the Kimi-Code engine now.

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

---

**Use `@moonshot-ai/klient` to connect to the Kimi-Code engine via memory or IPC transport, then interact through typed facades for global, session, and agent-level operations.**

The `@moonshot-ai/klient` package is the official, transport-agnostic client SDK for the [MoonshotAI/kimi-code](https://github.com/MoonshotAI/kimi-code) repository. It provides a unified interface to the **agent-core-v2** runtime, letting you build tools and extensions that talk to the Kimi-Code engine whether it runs in-process or across a Unix socket.

## What Is the `klient` Package?

At its core, `klient` exposes a **three-tier facade**—global, session, and agent—that mirrors the engine's RPC surface. The SDK abstracts away transport details so the same code works whether you're embedding the engine directly or connecting to a separate process.

The architecture centers on `createKlientFromChannel` in [`packages/klient/src/core/klient.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/klient/src/core/klient.ts). This factory builds a `Klient` instance from any object implementing the `KlientChannel` interface, which defines three low-level operations:

- `call` – synchronous RPC invocation
- `stream` – streaming response handling
- `listen` – bi-directional event subscription

## Transport Options for `klient` Integration

### Memory Transport (In-Process)

The memory transport runs the engine inside your Node.js process using a `MemoryDispatcher` that simulates JSON round-trips without actual serialization overhead.

```typescript
import { createKlient } from '@moonshot-ai/klient/memory';
import { bootstrap } from '@moonshot-ai/agent-core-v2';

const { app } = bootstrap(
  { homeDir: '/tmp/demo', clientIdentity: { name: 'my-app' } },
  [...logSeed(resolveLoggingConfig({ homeDir: '/tmp/demo', env: process.env }))]
);

const klient = createKlient({ scope: app });

```

**Implementation source**: [`packages/klient/src/transports/memory/index.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/klient/src/transports/memory/index.ts)

This approach minimizes latency and eliminates IPC overhead. Ideal for CLI tools, automated tests, and embedded assistants.

### IPC Transport (Separate Process)

The IPC transport connects to an engine process via Unix-domain socket, enabling multi-process architectures and remote engine hosting.

```typescript
import { createKlient } from '@moonshot-ai/klient/ipc';

const klient = createKlient({
  socketPath: '/var/run/kimi-code.sock',
  validate: true,  // runtime contract validation
});

```

**Implementation source**: [`packages/klient/src/transports/ipc/index.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/klient/src/transports/ipc/index.ts)

The companion `serveKlientIpc` function (from [`packages/klient/src/transports/ipc/host.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/klient/src/transports/ipc/host.ts)) starts the server side.

## The Three-Tier Facade System

Once connected, all `klient` instances expose the same typed interface regardless of transport.

### Global Facade

Access engine-wide capabilities through `klient.global`:

```typescript
const envInfo = await klient.global.env();
console.log(envInfo.platform, envInfo.homeDir);

const workspaces = await klient.global.workspaces.list();
const providers = await klient.global.kosong.listProviders();

```

**Implementation source**: [`packages/klient/src/core/facade/global.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/klient/src/core/facade/global.ts)

### Session Facade

Open a session handle to work with conversation-scoped APIs:

```typescript
const { id: sessionId } = await klient.global.sessions.create({ title: 'My Session' });
const session = klient.session(sessionId);

const answer = await session.questions.ask({ content: 'Explain quantum computing' });

```

**Implementation source**: [`packages/klient/src/core/facade/session.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/klient/src/core/facade/session.ts)

### Agent Facade

Interact with specific agents within a session for tool execution:

```typescript
const agent = session.agent('default');
const result = await agent.shell.runCommand({ command: 'uname -a' });
console.log(result.stdout, result.stderr, result.exitCode);

```

**Implementation source**: [`packages/klient/src/core/facade/agent.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/klient/src/core/facade/agent.ts)

## Event Subscription with `klient`

Every facade includes an `EventHub` that forwards engine events with automatic cleanup on client close.

```typescript
// Subscribe to provider changes
const subscription = klient.events.on('kosong.providers.changed', (event) => {
  console.log('Providers updated:', event.providers);
});

// Later: clean up
subscription.dispose();

```

The hub validates event payloads against `globalContract` and supports wildcards for namespaced events. **Implementation**: [`packages/klient/src/core/events/hub.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/klient/src/core/events/hub.ts).

## Complete Integration Example

This end-to-end example from [`packages/klient/examples/basic.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/klient/examples/basic.ts) demonstrates the full `klient` integration pattern:

```typescript
import { bootstrap, logSeed, resolveLoggingConfig } from '@moonshot-ai/agent-core-v2';
import { createKlient } from '@moonshot-ai/klient/memory';

async function run() {
  // 1. Bootstrap engine in-process
  const { app } = bootstrap(
    { homeDir: '/tmp/klient-demo', clientIdentity: { name: 'demo' } },
    [...logSeed(resolveLoggingConfig({ homeDir: '/tmp/klient-demo', env: process.env }))],
  );

  // 2. Create klient with memory transport
  const klient = createKlient({ scope: app });

  // 3. Global operations
  const envInfo = await klient.global.env();
  const sessions = await klient.global.sessions.list({});

  // 4. Event handling
  const sub = klient.events.on('kosong.providers.changed', console.log);

  // 5. Mutate state and observe events
  await klient.global.kosong.addProvider('demo', {
    type: 'openai',
    auth: { method: 'api-key', apiKey: 'demo-key' },
  });
  await klient.global.kosong.removeProvider('demo');

  // 6. Cleanup
  sub.dispose();
  await klient.close();
  app.dispose();
}

run().catch(console.error);

```

## Configuration and Performance Options

Control `klient` behavior via `KlientOptions`:

| Option | Default | Purpose |
|--------|---------|---------|
| `validate` | `true` | Validate all wire payloads against `globalContract` |
| `socketPath` | required for IPC | Unix socket path for IPC transport |
| `scope` | required for memory | Bootstrapped engine scope from `agent-core-v2` |

Disable validation for hot-path performance: `validate: false`.

## Summary

- **`@moonshot-ai/klient`** is the transport-agnostic SDK for Kimi-Code engine integration
- **Memory transport** (`klient/memory`) embeds the engine in-process via [`packages/klient/src/transports/memory/index.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/klient/src/transports/memory/index.ts)
- **IPC transport** (`klient/ipc`) connects via Unix socket through [`packages/klient/src/transports/ipc/index.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/klient/src/transports/ipc/index.ts)
- **Three-tier facade**—global, session, agent—provides typed access to all engine capabilities
- **Event hub** ([`packages/klient/src/core/events/hub.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/klient/src/core/events/hub.ts)) subscribes to engine events with automatic cleanup
- **Contract validation** catches API drift; disable with `validate: false` for performance

## Frequently Asked Questions

### What is the difference between memory and IPC transport in `klient`?

**Memory transport** runs the engine inside your Node.js process using a `MemoryDispatcher`, eliminating serialization overhead and enabling direct function calls. **IPC transport** communicates via Unix-domain socket with a separately launched engine process, supporting distributed architectures and process isolation. The same facade code works unchanged—only the `createKlient` import and configuration differ.

### How do I subscribe to engine events when integrating with `klient`?

Use `klient.events.on(eventName, handler)` from any `Klient` instance. The `EventHub` in [`packages/klient/src/core/events/hub.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/klient/src/core/events/hub.ts) forwards typed events like `'kosong.providers.changed'`. Returns a disposable subscription; call `.dispose()` or `await klient.close()` to clean up. Events are validated against the contract unless `validate: false` is set.

### Can I disable payload validation for better performance?

Yes. Set `validate: false` in `KlientOptions` when calling `createKlient`. This skips runtime validation against `globalContract` for all RPC calls and events. Recommended only in production environments where you control both client and engine versions, since mismatched contracts will fail silently rather than throwing descriptive errors.

### Where is the public API surface defined in the `klient` package?

[`packages/klient/src/index.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/klient/src/index.ts) re-exports all public types and factories: `Klient`, `SessionHandle`, `AgentHandle`, `GlobalFacade`, `SessionFacade`, `AgentFacade`, and transport-specific `createKlient` functions. This is your single import target—avoid deep imports from internal paths to ensure forward compatibility.