Kimi-Code Monorepo Package Structure: How Apps and Libraries Are Organized

The Kimi-Code repository organizes code into two top-level directories—apps/ for end-user applications and packages/ for reusable libraries—managed via pnpm workspaces with internal path aliases and workspace dependencies.

The MoonshotAI/kimi-code repository is a TypeScript monorepo that separates deployable applications from consumable libraries through a strict two-tier directory structure. Understanding how packages are organized within the monorepo structure is essential for navigating the codebase, contributing to the agent engine, or consuming the public SDK. The architecture relies on pnpm workspaces to link everything under apps/* and packages/* while maintaining clear boundaries between the CLI front-end, web interfaces, and core engine logic.

Top-Level Organization: apps/ vs packages/

The repository splits all code into two distinct categories at the root level, each serving different deployment and consumption patterns.

Applications in apps/

The apps/ directory contains end-user applications that run in terminals, browsers, or as visual debugging tools. Each application consumes the core libraries through workspace dependencies rather than direct low-level engine imports.

• apps/kimi-code – The CLI/TUI front-end defined in apps/kimi-code/package.json and bootstrapped from apps/kimi-code/src/main.ts
• apps/kimi-web – The Vue-based web UI (see apps/kimi-web/AGENTS.md) with its entry point at apps/kimi-web/src/main.ts
• apps/kimi-inspect – A web inspector for the server (apps/kimi-inspect/package.json)
• apps/vis – Visual debugging tools with server and web sub-folders (apps/vis/package.json)

Libraries in packages/

The packages/ directory hosts reusable libraries published as workspace modules under the @moonshot-ai scope. These provide the agent engine, SDKs, LLM abstractions, and data stores.

• packages/agent-core – The unified agent engine (packages/agent-core/package.json), with entry point packages/agent-core/src/agent/index.ts
• packages/agent-core-v2 – The v2 engine used by the server (packages/agent-core-v2/package.json)
• packages/node-sdk – Public TypeScript SDK for consumers (packages/node-sdk/package.json), exposing its surface via packages/node-sdk/src/index.ts
• packages/kosong – LLM/provider abstraction layer (packages/kosong/package.json)
• packages/kaos – Execution-environment utilities (packages/kaos/package.json)
• packages/oauth – OAuth helpers (packages/oauth/package.json)
• packages/telemetry – Client-side telemetry (packages/telemetry/package.json)
• packages/transcript – Isomorphic transcript data layer (packages/transcript/package.json), with contract definitions in packages/transcript/src/contract/schema.ts
• packages/minidb – Embedded JSON document store for search indices (packages/minidb/package.json)
• packages/klient – Client utilities for API interaction
• packages/kap-server – Server bootstrap logic (packages/kap-server/src/start.ts)
• packages/tree-sitter-bash – Syntax parsing utilities

Workspace Configuration and Build Orchestration

The monorepo defines its workspace boundaries in pnpm-workspace.yaml, which automatically includes all directories under apps/* and packages/*. Because the project also builds with Nix, the same package list is mirrored in flake.nix to ensure reproducible builds across environments. This dual-configuration approach keeps the workspace definition synchronized between pnpm and Nix-based build pipelines.

Internal Package Architecture and Import Patterns

Each package configures its public API surface through the exports field in package.json, while internal path aliases are mapped under the "imports" field using the #/* pattern pointing to ./src/*.ts.

This enables two distinct import styles within the codebase:

// Public workspace import (uses exports field)
import { Agent } from '@moonshot-ai/agent-core'

// Internal package import using alias (uses imports field)
import { Session } from '#/session'

Dependency Flow Between Layers

Applications in apps/ depend on packages using the workspace:^ protocol in their package.json files. This resolution strategy ensures that apps always reference the latest built version of local packages without requiring a separate publish step to a remote registry. For instance, the CLI application consumes the core engine while the web interface relies on the same underlying packages through this workspace linkage.

Practical Usage Examples

The following examples demonstrate how different layers of the monorepo interact according to the source code.

Creating an agent from the core engine:

import { Agent } from '@moonshot-ai/agent-core'
import { Session } from '@moonshot-ai/agent-core/session'

const session = new Session({ id: 'demo' })
const agent = new Agent({ session })
await agent.start()

Using the public SDK in a consumer project:

import { Klient } from '@moonshot-ai/klient'

const client = new Klient({ baseUrl: 'http://localhost:58627' })
const sessions = await client.global.listSessions()
console.log(sessions)

Accessing the transcript layer directly:

import { TranscriptService } from '@moonshot-ai/transcript'

const transcript = await TranscriptService.fetch({ sessionId: 'abc', agentId: 'default' })
console.log(transcript.turns)

Summary

• The Kimi-Code monorepo divides code into apps/ (deployable applications) and packages/ (reusable libraries) at the repository root.
• Workspace membership is controlled by pnpm-workspace.yaml and mirrored in flake.nix for Nix builds.
• Packages use exports in package.json for public APIs and "imports" with #/* aliases for internal module resolution.
• Applications consume libraries via workspace:^ dependencies, ensuring immediate access to local changes without publishing.
• Key architectural boundaries separate the TUI (kimi-code), web UI (kimi-web), core engine (agent-core), and public SDK (node-sdk).

Frequently Asked Questions

What is the difference between agent-core and agent-core-v2?

According to the MoonshotAI/kimi-code source code, packages/agent-core contains the unified agent engine, while packages/agent-core-v2 serves as the v2 engine specifically used by the server. This separation allows the team to iterate on the engine architecture while maintaining backward compatibility for existing applications that depend on the original core.

How do I import internal modules within a package?

You can use the #/* alias defined in the package's package.json imports field. For example, import { Session } from '#/session' resolves to ./src/session.ts relative to the package root. This convention keeps internal imports concise and distinguishes them from external workspace dependencies.

Why does the monorepo use both pnpm and Nix configuration files?

The pnpm-workspace.yaml file defines the workspace boundaries for JavaScript dependency management, while flake.nix mirrors the same package list to provide reproducible system-level builds. This dual configuration ensures that the monorepo can be built consistently both in Node.js environments and in Nix-based CI/CD pipelines.

Can I use the @moonshot-ai packages in external projects?

Yes, the packages/node-sdk directory contains the public TypeScript SDK designed for external consumers. As implemented in MoonshotAI/kimi-code, this package exposes a stable API surface that you can import and use in your own applications, while internal packages like agent-core are intended primarily for first-party app consumption.

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