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

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):

• 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) 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 — 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

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

2. Install Workspace Dependencies

pnpm install

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

3. Build the Shared Packages

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:

pnpm run build:vis-asset

This runs 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/apps/kimi-code/src/generated/vis-web-asset.ts)

5. Bundle the CLI

pnpm run build

This executes tsdown with configuration from [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/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

6. Run the Built CLI

./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) under the "bin" field.

7. Run Tests

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:

# 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/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 (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)	Monorepo workspace definition
[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/apps/kimi-code/tsdown.config.ts)	Bundler configuration: entry, aliases, build definitions
scripts/check-web-assets.mjs	Verifies dist-web/index.html exists before packaging
scripts/build-vis-asset.mjs	Generates gzipped vis web asset as base64 module
[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	Orchestrates native bundling with worker support

Complete Build Commands Reference

# 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 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 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/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 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.

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