How to Build the kimi-code Project: Complete Monorepo Setup Guide

To build the kimi-code project, clone the MoonshotAI/kimi-code repository, install dependencies with pnpm, and run pnpm build to compile the CLI, web UI, and shared libraries from the monorepo source.

The kimi-code repository is a monorepo containing the CLI/TUI application (apps/kimi-code), the web interface (apps/kimi-web), and supporting libraries that power the agent engine. This guide covers the complete build process from initial setup through production bundling, referencing the actual build scripts and configuration files as implemented in the source code.

Prerequisites: Node.js and pnpm Versions

Before building, ensure your environment meets the minimum version requirements specified in the root README.md:

• Node.js ≥ 24.15.0
• pnpm 10.33.0

These requirements are enforced in the engine fields of package.json and documented in the development setup section (lines 97-103 of README.md). Using older versions may result in dependency resolution errors or build failures.

Clone and Install Dependencies

Start by cloning the repository and installing all workspace dependencies:

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

The pnpm install command reads pnpm-workspace.yaml at the repository root, which defines the monorepo structure to include all packages under packages/* and apps/*. This ensures shared dependencies are hoisted and linked correctly across the CLI, web UI, and library packages.

Building the Monorepo

The root package.json orchestrates build commands across all workspaces. Depending on your development needs, you can build the entire project or target specific applications.

Full Production Build

To compile every package in the workspace:

pnpm build

This script iterates over each workspace defined in pnpm-workspace.yaml and compiles TypeScript to dist/ directories (or dist-web for the web UI), handling the dependency graph automatically so libraries build before applications that depend on them.

CLI-Only Development

If you are working exclusively on the TUI/CLI component (apps/kimi-code), start it in watch mode for rapid iteration:

pnpm dev:cli

This command mounts the CLI with hot reloading, bypassing the web UI build steps to reduce startup time.

Web UI Development

The web client (apps/kimi-web) is a Vue 3 + Vite application. To run it locally against a real server:

pnpm dev:web

# Or directly:

pnpm -C apps/kimi-web run dev

According to apps/kimi-web/README.md (lines 21-30), the Vite development server proxies /api/v1 requests to the local kap-server at http://127.0.0.1:58627. This allows the frontend to communicate with the agent backend during development.

Bundling the Web UI into the CLI

For production releases, the web UI assets must be embedded within the CLI package so that the kimi web command can serve them statically. This requires a two-step build process:

# Step 1: Build the web UI to apps/kimi-web/dist

pnpm -C apps/kimi-web run build

# Step 2: Copy assets into the CLI package

pnpm -C apps/kimi-code run build

The second command executes scripts/copy-web-assets.mjs, which copies the compiled web assets from apps/kimi-web/dist into the CLI package as dist-web. As documented in apps/kimi-web/README.md (lines 91-96), this bundling step ensures the CLI can serve the web interface without requiring separate deployment of the web assets.

Testing and Verification

After building, verify the codebase integrity using the root-level verification scripts:

# Run unit and e2e tests across all workspaces

pnpm test

# TypeScript type checking

pnpm typecheck

# Linting with oxlint

pnpm lint

These commands use the monorepo configuration to run tests in dependency order, ensuring that changes in shared libraries are validated against all consuming applications.

Summary

• Install dependencies with pnpm install after cloning, ensuring Node.js ≥ 24.15.0 and pnpm 10.33.0.
• Build the entire monorepo with pnpm build, which compiles all packages in packages/* and apps/* according to pnpm-workspace.yaml.
• Develop the CLI using pnpm dev:cli or the web UI using pnpm dev:web, which proxies API calls to the local kap-server.
• Bundle web assets into the CLI by running pnpm -C apps/kimi-web run build followed by pnpm -C apps/kimi-code run build, which triggers scripts/copy-web-assets.mjs.
• Verify builds with pnpm test, pnpm typecheck, and pnpm lint.

Frequently Asked Questions

What versions of Node.js and pnpm does kimi-code require?

The project requires Node.js 24.15.0 or higher and pnpm 10.33.0, as specified in the root README.md (lines 97-103) and enforced in the package.json engine fields. Using version managers like nvm or fnm is recommended to maintain compatibility with these specific requirements.

How do I run only the CLI without building the web UI?

Use the pnpm dev:cli command from the repository root. This starts the CLI/TUI in development mode with hot reloading without compiling the Vue web application, significantly reducing startup time when you only need the terminal interface.

Why does the CLI package need to bundle the web UI assets?

The kimi web command serves the web interface statically from within the CLI package. According to the build logic in scripts/copy-web-assets.mjs, the production build copies the Vite-generated assets from apps/kimi-web/dist into apps/kimi-code/dist-web, allowing the CLI to launch a self-contained web server without external dependencies.

How do I verify the build succeeded?

Run pnpm test to execute the unit and end-to-end test suites, pnpm typecheck to validate TypeScript types across all workspaces, and pnpm lint to run oxlint against the source. These commands confirm that the monorepo compiles correctly and maintains code quality standards.

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