# How to Build Kimi-Code from Source: A Complete Guide to the TypeScript Monorepo

> Build Kimi-Code from source with this guide. Learn to clone the repo, install dependencies using pnpm, and bundle the CLI to create your own Kimi-Code distribution.

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

---

**To build Kimi-Code from source, clone the repository, install dependencies with pnpm, build the shared packages with `pnpm run build:packages`, then bundle the CLI with `pnpm run build` to produce `dist/main.mjs`.**

Kimi-Code is MoonshotAI's terminal-based AI coding assistant. This guide walks through building the entire TypeScript monorepo from source, including the CLI application, shared agent packages, and optional native binaries. All steps are based on the actual source structure as implemented in `MoonshotAI/kimi-code`.

## Prerequisites for Building Kimi-Code

Before starting, ensure your environment meets the engine requirements specified in the root [[`package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/package.json)](https://github.com/MoonshotAI/kimi-code/blob/main/package.json):

- **Node.js** ≥ 24.15.0
- **pnpm** ≥ 10.33.0

The workspace configuration in [[`pnpm-workspace.yaml`](https://github.com/MoonshotAI/kimi-code/blob/main/pnpm-workspace.yaml)](https://github.com/MoonshotAI/kimi-code/blob/main/pnpm-workspace.yaml) defines the monorepo structure that pnpm uses to resolve cross-package dependencies.

## Understanding the Monorepo Structure

Kimi-Code organizes code across three layers. Understanding this helps troubleshoot build issues.

### `apps/` — Runnable Applications

The CLI lives in `apps/kimi-code`. It contains:

- **[`src/main.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/main.ts)** — The entry point exported as the `kimi` binary
- Build scripts that bundle the CLI and embed web UI assets
- Native packaging scripts in `scripts/native/`

### `packages/` — Shared Libraries

These must build before the CLI:

- **`packages/agent-core`** — Core agent engine
- **`packages/agent-core-v2`** — Next-generation engine
- **`packages/klient`** — Client SDK
- **`packages/transcript`** — Transcript layer
- **`packages/minidb`** — Embedded JSON store

### `docs/` — Generated Documentation

Contains guides and API documentation generated from source.

## Step-by-Step Build Instructions

### 1. Clone the Repository

```bash
git clone https://github.com/MoonshotAI/kimi-code.git
cd kimi-code

```

### 2. Install Workspace Dependencies

```bash
pnpm install

```

This resolves dependencies across all packages according to [[`pnpm-workspace.yaml`](https://github.com/MoonshotAI/kimi-code/blob/main/pnpm-workspace.yaml)](https://github.com/MoonshotAI/kimi-code/blob/main/pnpm-workspace.yaml).

### 3. Build the Shared Packages

```bash
pnpm run build:packages

```

This runs the `build` script for every package under `packages/*`, compiling the agent core, transcript, minidb, and other dependencies that the CLI requires.

### 4. Generate and Bundle the Visual Debug Asset

The CLI embeds a web-based visual debugger. The `prebuild` script automatically invokes:

```bash
pnpm run build:vis-asset

```

This runs [`scripts/build-vis-asset.mjs`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/scripts/build-vis-asset.mjs), which:

- Builds the single-file `vis` UI
- Gzips the output
- Creates the embed module at [[`src/generated/vis-web-asset.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/generated/vis-web-asset.ts)](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/src/generated/vis-web-asset.ts)

### 5. Bundle the CLI

```bash
pnpm run build

```

This executes [`tsdown`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/tsdown.config.ts) with configuration from [[`tsdown.config.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/tsdown.config.ts)](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/tsdown.config.ts), which:

- Bundles TypeScript from [[`src/main.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/main.ts)](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/src/main.ts) into `dist/main.mjs`
- Injects the built-in catalog definition
- Adds a shebang for direct execution
- Verifies the pre-built web bundle via [`scripts/check-web-assets.mjs`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/scripts/check-web-assets.mjs)

### 6. Run the Built CLI

```bash
./dist/main.mjs --version

# or

node dist/main.mjs --version

```

The binary entry is defined in [[`apps/kimi-code/package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/package.json)](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/package.json) under the `"bin"` field.

### 7. Run Tests

```bash
pnpm test    # Unit tests across packages

pnpm e2e     # End-to-end tests against built packages

```

## Building Native Binaries (Optional)

For distribution without requiring Node.js, Kimi-Code supports native compilation through the scripts in [`scripts/native/01-bundle.mjs`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/scripts/native/01-bundle.mjs):

```bash

# JavaScript bundle for native runtime

pnpm run build:native:js

# Single-executable archive (SEA)

pnpm run build:native:sea

# Final native binary with pkg-pr-new

pnpm run package:native

```

The native build chain:
1. Builds visual assets
2. Runs `tsdown` with [[`tsdown.native.config.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/tsdown.native.config.ts)](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/tsdown.native.config.ts) for worker thread support
3. Packages the result with `pkg-pr-new`

## Key Build Files Reference

| File | Purpose |
|------|---------|
| [[`package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/package.json) (root)](https://github.com/MoonshotAI/kimi-code/blob/main/package.json) | Workspace declaration, engine requirements, top-level scripts |
| [[`pnpm-workspace.yaml`](https://github.com/MoonshotAI/kimi-code/blob/main/pnpm-workspace.yaml)](https://github.com/MoonshotAI/kimi-code/blob/main/pnpm-workspace.yaml) | Monorepo workspace definition |
| [[`apps/kimi-code/package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/package.json)](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/package.json) | CLI metadata, binary entry, build scripts |
| [[`tsdown.config.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/tsdown.config.ts)](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/tsdown.config.ts) | Bundler configuration: entry, aliases, build definitions |
| [`scripts/check-web-assets.mjs`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/scripts/check-web-assets.mjs) | Verifies [`dist-web/index.html`](https://github.com/MoonshotAI/kimi-code/blob/main/dist-web/index.html) exists before packaging |
| [`scripts/build-vis-asset.mjs`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/scripts/build-vis-asset.mjs) | Generates gzipped `vis` web asset as base64 module |
| [[`src/main.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/main.ts)](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/src/main.ts) | CLI entry point, compiled to `dist/main.mjs` |
| [`scripts/native/01-bundle.mjs`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/scripts/native/01-bundle.mjs) | Orchestrates native bundling with worker support |

## Complete Build Commands Reference

```bash

# Full build from clean checkout

git clone https://github.com/MoonshotAI/kimi-code.git
cd kimi-code
pnpm install
pnpm run build:packages
pnpm run build

# Development workflow (with hot reload)

pnpm run dev  # defined in apps/kimi-code/package.json

# Verification

./dist/main.mjs --version
pnpm test

```

## Summary

- **Kimi-Code** is a TypeScript monorepo requiring Node ≥ 24.15.0 and pnpm ≥ 10.33.0
- Build order matters: workspace dependencies → shared packages → visual assets → CLI bundle
- The `pnpm run build:packages` command compiles all `packages/*` before the CLI can bundle
- `pnpm run build` in `apps/kimi-code` produces the executable `dist/main.mjs` using `tsdown`
- The visual debugger is auto-generated at [`src/generated/vis-web-asset.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/generated/vis-web-asset.ts) and embedded as base64
- Native binaries are built via `pnpm run build:native:js`, `build:native:sea`, and `package:native`

## Frequently Asked Questions

### What version of Node.js is required to build Kimi-Code?

Node.js **≥ 24.15.0** is required, as specified in the root [`package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/package.json) `engine` field. The build uses modern Node features and will fail on earlier versions. pnpm `≥ 10.33.0` is also required for workspace dependency resolution.

### Why does the build fail with missing web asset errors?

The CLI requires a pre-built visual debugger bundle. Run `pnpm run build:vis-asset` to generate [[`src/generated/vis-web-asset.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/generated/vis-web-asset.ts)](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/src/generated/vis-web-asset.ts), or let the `prebuild` script handle it automatically. The check in [`scripts/check-web-assets.mjs`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/scripts/check-web-assets.mjs) enforces this before bundling.

### Can I build Kimi-Code without installing Node.js on target machines?

Yes. Use the native build chain: `pnpm run build:native:js` creates a JavaScript bundle for the native runtime, `build:native:sea` produces a single-executable archive, and `package:native` creates the final distributable binary using `pkg-pr-new`.