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

> Discover how Kimi-Code organizes its monorepo with apps and packages managed by pnpm workspaces. Learn about internal path aliases and workspace dependencies for efficient development.

- Repository: [Moonshot AI/kimi-code](https://github.com/MoonshotAI/kimi-code)
- Tags: architecture
- Published: 2026-07-29

---

**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`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/package.json) and bootstrapped from [`apps/kimi-code/src/main.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/src/main.ts)
- `apps/kimi-web` – The Vue-based web UI (see [`apps/kimi-web/AGENTS.md`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-web/AGENTS.md)) with its entry point at [`apps/kimi-web/src/main.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-web/src/main.ts)
- `apps/kimi-inspect` – A web inspector for the server ([`apps/kimi-inspect/package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-inspect/package.json))
- `apps/vis` – Visual debugging tools with `server` and `web` sub-folders ([`apps/vis/package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/package.json)), with entry point [`packages/agent-core/src/agent/index.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/agent/index.ts)
- `packages/agent-core-v2` – The v2 engine used by the server ([`packages/agent-core-v2/package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/package.json))
- `packages/node-sdk` – Public TypeScript SDK for consumers ([`packages/node-sdk/package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/node-sdk/package.json)), exposing its surface via [`packages/node-sdk/src/index.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/node-sdk/src/index.ts)
- `packages/kosong` – LLM/provider abstraction layer ([`packages/kosong/package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/kosong/package.json))
- `packages/kaos` – Execution-environment utilities ([`packages/kaos/package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/kaos/package.json))
- `packages/oauth` – OAuth helpers ([`packages/oauth/package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/oauth/package.json))
- `packages/telemetry` – Client-side telemetry ([`packages/telemetry/package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/telemetry/package.json))
- `packages/transcript` – Isomorphic transcript data layer ([`packages/transcript/package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/transcript/package.json)), with contract definitions in [`packages/transcript/src/contract/schema.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/transcript/src/contract/schema.ts)
- `packages/minidb` – Embedded JSON document store for search indices ([`packages/minidb/package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/minidb/package.json))
- `packages/klient` – Client utilities for API interaction
- `packages/kap-server` – Server bootstrap logic ([`packages/kap-server/src/start.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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:

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

```ts
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:**

```ts
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:**

```ts
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`](https://github.com/MoonshotAI/kimi-code/blob/main/pnpm-workspace.yaml) and mirrored in `flake.nix` for Nix builds.
- Packages use `exports` in [`package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/package.json) imports field. For example, `import { Session } from '#/session'` resolves to [`./src/session.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/./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`](https://github.com/MoonshotAI/kimi-code/blob/main/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.