Purpose of Each Package in Kimi-Code: Complete Architecture Guide

The Kimi-Code monorepo organizes its functionality into 13 distinct TypeScript packages, ranging from the core agent engine (agent-core) to terminal UI primitives (pi-tui), each handling a specific layer of the AI agent execution stack.

The Kimi-Code repository from MoonshotAI is a TypeScript monorepo designed to power AI agent execution with clean separation of concerns. Understanding the purpose of each package in kimi-code reveals a layered architecture that isolates the agent engine, server runtime, client SDK, and specialized utilities into modular, testable units. This guide explains every package based on the actual source code structure and implementation details found in the repository.

Core Agent Engine and Runtime

agent-core: The Unified Agent Engine

Located in packages/agent-core/, this package defines the fundamental Agent and Session abstractions that drive the entire system. It implements dependency injection containers, services, skills, tools, flags, and the execution model that powers all agent operations.

According to the Kimi-Code source code, packages/agent-core/src/agent/Agent.ts contains the core Agent class implementation that orchestrates tool execution and state management. This package is consumed by the server (kap-server) to run agents and by the SDK to expose a stable public API.

kap-server: REST and WebSocket API Host

The kap-server package implements the runtime host that exposes the REST / WebSocket API via /api/v1/* endpoints. As implemented in packages/kap-server/src/start.ts, this server bootstraps a DI container, registers debug routes, and streams transcript data to connected clients.

This package powers both the CLI (kimi-code) and the web UI, acting as the bridge between client requests and the core agent engine.

Client SDK and Transport Layer

node-sdk: Public TypeScript SDK

Published as @moonshot-ai/kimi-code-sdk, the node-sdk provides typed client classes including Klient, Session, and Agent for external developers. The public API entry point resides in packages/node-sdk/src/index.ts, offering a stable contract for third-party integrations.

This package is bundled into the published @moonshot-ai/kimi-code package and is used by the CLI, web UI, and external codebases.

klient: Low-Level Transport Abstraction

Internal to the SDK, the klient package handles IPC, memory, and HTTP transport implementations for communicating with the server. The Klient.ts file at packages/klient/src/Klient.ts wraps transport-specific details, abstracting the communication mechanism between consumers and the server.

This layer includes end-to-end test harnesses and is responsible for managing connection lifecycles across different environments.

Data Management and Model Resolution

transcript: Isomorphic Transcript Store

This package provides an isomorphic transcript store that tracks L1/L2/L3/L4 transcript layers and manages op-batch sequencing. Used by the server to record agent activity and by the UI to render chat history efficiently, it provides a contract-driven API for both browser and Node environments.

Key contract definitions for op-batch sequencing live in packages/transcript/src/contract/schema.ts, ensuring consistent data structures across the stack.

kosong: LLM Provider Abstraction

The kosong package resolves model configuration through ModelCatalog and ModelService classes. Located in packages/kosong/src/catalog/ModelCatalog.ts, this layer enables agents to request models uniformly across providers (OpenAI, Anthropic, etc.) via environment variables, overrides, and defaults.

This abstraction allows the system to switch between different LLM backends without modifying the agent core logic.

Execution Environment

kaos: Safe Process Execution

Providing the execution environment for agents, kaos wraps process spawning, SSH connections, and filesystem utilities. The packages/kaos/src/ssh/ssh.ts file contains SSH helper utilities that allow agents to run external commands safely and testably.

This package provides the primitives that agents use when they need to execute shell commands, spawn processes, or interact with remote systems.

User Interface and Language Support

pi-tui: Terminal UI Primitives

Based on pi-mono, this lightweight terminal UI library offers widgets, rendering, and input handling without pulling in heavy UI frameworks. The Terminal.ts file at packages/pi-tui/src/Terminal.ts powers the TUI application located in apps/kimi-code.

This package enables rich terminal interfaces while maintaining minimal dependencies and fast rendering performance.

tree-sitter-bash: Pure TypeScript Bash Parser

A deterministic budgeted parser that generates ASTs for Bash scripts without requiring external native dependencies. The packages/tree-sitter-bash/src/parser.ts entry point supports tools that analyze shell code, such as permission matching utilities.

This pure-TypeScript implementation allows the system to parse and analyze Bash scripts in constrained environments where native binaries are unavailable.

Integration and Compatibility Layers

acp-adapter: Agent-Control-Protocol Bridge

The acp-adapter translates external Agent-Control-Protocol (ACP) messages into internal service calls. Defined in packages/acp-adapter/src/adapter.ts, this adapter allows external tooling that speaks ACP to control agents through the server.

This enables interoperability with external systems and tools that implement the ACP specification.

migration-legacy: Version Migration Shim

This compatibility package migrates data from the legacy v1 engine to the current v2 architecture. The packages/migration-legacy/src/migrate.ts routine runs during upgrades to ensure older sessions still load correctly.

This shim ensures backward compatibility and prevents data loss when upgrading between major versions of the platform.

telemetry: Usage Analytics

Collecting anonymized diagnostics data with opt-out support, the telemetry package instruments user interactions across the CLI and web UI. Implementation resides in packages/telemetry/src/Telemetry.ts, providing shared client-side telemetry for product improvement and diagnostics.

Practical Usage Examples

Below are typical import patterns that illustrate how these packages interact in practice:

// Create a client that talks to a running Kimi server
import { Klient } from '@moonshot-ai/klient';
const client = new Klient({ baseUrl: 'http://localhost:58627' });

// Start a new session and run an agent
import { Session } from '@moonshot-ai/kimi-code-sdk';
const session = await client.session.create();
await session.agent.run({ prompt: 'Explain quantum entanglement' });

// Access the transcript store directly (used by the web UI)
import { TranscriptService } from '@moonshot-ai/transcript';
const transcript = TranscriptService.forSessionLive(session.id);

// Use the model catalog to pick a model
import { ModelCatalog } from '@moonshot-ai/kosong';
const model = await ModelCatalog.getDefault();

// Run a Bash command via the Kaos execution layer
import { spawn } from '@moonshot-ai/kaos';
await spawn('ls', ['-l', '/home/user']);

Summary

• agent-core defines the fundamental Agent and Session classes in packages/agent-core/src/agent/Agent.ts, serving as the execution engine.
• kap-server hosts the REST/WebSocket API via packages/kap-server/src/start.ts, connecting clients to the agent core.
• node-sdk and klient provide the public TypeScript SDK and transport abstraction for external developers.
• transcript manages multi-layer conversation history through packages/transcript/src/contract/schema.ts.
• kosong handles LLM provider resolution via ModelCatalog in packages/kosong/src/catalog/ModelCatalog.ts.
• kaos supplies safe execution primitives for process spawning and SSH operations.
• pi-tui and tree-sitter-bash handle terminal UI and Bash parsing without heavy dependencies.
• acp-adapter, migration-legacy, and telemetry handle protocol integration, data migration, and analytics respectively.

Frequently Asked Questions

What is the difference between agent-core and kap-server in kimi-code?

agent-core contains the business logic for agent execution, including the Agent class, sessions, and tool definitions, while kap-server is the infrastructure layer that exposes these capabilities via HTTP/WebSocket endpoints. The server imports and instantiates classes from agent-core but adds network transport, routing, and client session management.

Which package should I use to build a custom client for kimi-code?

Use node-sdk (@moonshot-ai/kimi-code-sdk) for building third-party applications, as it provides the stable public API including Klient, Session, and Agent classes. The klient package handles low-level transport details internally, so most developers should interact with the higher-level SDK rather than the transport layer directly.

How does kimi-code handle different LLM providers like OpenAI and Anthropic?

The kosong package abstracts provider-specific details through the ModelCatalog and ModelService classes defined in packages/kosong/src/catalog/ModelCatalog.ts. This allows the agent-core engine to request models by capability rather than provider, with configuration resolved via environment variables and config overrides.

Where does kimi-code store conversation history and transcript data?

The transcript package manages conversation history across both browser and Node environments, implementing L1/L2/L3/L4 layer tracking and op-batch sequencing as defined in packages/transcript/src/contract/schema.ts. The server writes transcript data through this package, while the web UI reads from it to render chat history efficiently.

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