# How to Set Up the Development Environment for Kimi Code: A Complete Guide

> Set up the Kimi Code development environment easily. Follow this guide to install Node.js and pnpm, clone the repository, and launch the CLI or web UI for Kimi Code.

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

---

**To set up the development environment for Kimi Code, install Node.js ≥24.15.0 and pnpm 10.33.0, clone the MoonshotAI/kimi-code repository, run `pnpm install`, and launch the CLI with `pnpm dev:cli` or the web UI with `pnpm dev:web`.**

Kimi Code is a TypeScript monorepo developed by MoonshotAI that ships a terminal-based AI coding agent alongside a Vue 3 web interface and modular server packages. To set up the development environment for kimi-code correctly, you must prepare the specific toolchain versions that enforce strict engine requirements according to the root [`package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/package.json), then leverage the workspace-aware build system to run individual components in development mode.

## Prerequisites

Before cloning the repository, ensure your system meets the following requirements defined in the source configuration:

- **Node.js** ≥24.15.0 (engine-strict is enforced in [`package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/package.json) lines 63-65)
- **pnpm** 10.33.0 (specified in the `packageManager` field of [`package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/package.json))
- **Git** for version control
- **Windows-specific**: Git for Windows and the `KIMI_SHELL_PATH` environment variable if your Bash binary resides outside the default path (see the Windows installation note in [`README.md`](https://github.com/MoonshotAI/kimi-code/blob/main/README.md))

On macOS or Linux, you can use the binary installer ([`install.sh`](https://github.com/MoonshotAI/kimi-code/blob/main/install.sh)) for quick testing without Node, but development work requires the full Node.js and pnpm toolchain.

## Repository Architecture

Kimi Code organizes code as a **workspace-aware monorepo** controlled by [`pnpm-workspace.yaml`](https://github.com/MoonshotAI/kimi-code/blob/main/pnpm-workspace.yaml). Understanding this structure helps you navigate the codebase after you set up the development environment.

### Key Applications

- **`apps/kimi-code`** – The CLI/TUI front-end that drives agent sessions. It consumes the SDK but remains independent from the core engine. Entry point: [`src/main.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/main.ts).
- **`apps/kimi-web`** – Vue 3 web UI that communicates with the server via `/api/v1`. It re-implements wire types locally to avoid direct core dependencies.
- **`apps/kimi-inspect`** – Web inspector for the `kap-server` debug surface, providing session explorers and state views.
- **`apps/vis`** – Visual debugging tools for session replays.

### Core Packages

- **`packages/agent-core`** – The unified agent engine containing Agent, Session, DI service layer, skills, and tools.
- **`packages/kap-server`** – The backend that hosts the agent engine, exposing REST and WebSocket APIs. Bootstrap file: [`src/start.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/start.ts).
- **`packages/transcript`** – Isomorphic transcript data layer (L1 store through L4 view registry) containing all wire contracts.
- **`packages/node-sdk`** – Public TypeScript SDK wrapping the core engine for external consumption.
- **`packages/klient`** – Contract-driven client SDK used by apps and tests.

Critical configuration files include [`AGENTS.md`](https://github.com/MoonshotAI/kimi-code/blob/main/AGENTS.md) (the definitive project map and coding conventions), [`pnpm-workspace.yaml`](https://github.com/MoonshotAI/kimi-code/blob/main/pnpm-workspace.yaml) (workspace declaration), and `flake.nix` (Nix build definition that must stay synchronized with the workspace file).

## Step-by-Step Setup Guide

Follow these commands to configure your local environment and start development servers.

### 1. Clone the Repository

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

```

### 2. Install Dependencies

The `pnpm install` command respects the workspace layout and executes a single install for all packages. It also runs the post-install script `scripts/fix-node-pty-perms.mjs` to correct permission issues.

```bash
pnpm install

```

### 3. Launch Development Servers

Choose the component you want to run:

**CLI/TUI (most common entry point):**

```bash
pnpm dev:cli                # Default backend (v1)

pnpm dev:cli:v2            # Experimental v2 backend with feature flags

pnpm dev:cli:marketplace   # With marketplace plugin URL

```

**Web UI:**

```bash
pnpm dev:web   # Starts Vite dev server (typically http://localhost:5173)

```

**Server Only (for backend development):**

```bash
pnpm dev:server       # Starts kap-server without UI

pnpm dev:kap-server   # Alias for above

pnpm dev:v2           # Multi-backend server (v1 + v2)

```

### 4. Run Tests

Verify the workspace builds correctly across all packages:

```bash
pnpm test           # Vitest suite across all packages

pnpm test:watch     # Watch mode for rapid feedback

pnpm test:coverage  # Generate coverage report

```

### 5. Type Checking and Linting

Ensure code quality before committing:

```bash
pnpm typecheck     # Full TypeScript compilation

pnpm lint          # Run oxlint in type-aware mode

pnpm lint:fix      # Auto-fix lint errors where possible

```

### 6. Build the Monorepo

Produce distributable artifacts for all packages:

```bash
pnpm build   # Executes pnpm -r run build across the workspace

```

## Troubleshooting Common Issues

When you set up the development environment for kimi-code, you may encounter these specific constraints:

**Engine Strictness Errors**

If `pnpm install` aborts with an engine mismatch error, your Node.js version is older than 24.15.0. Use a version manager (`nvm`, `fnm`, or `mise`) to select the correct version, as the root [`package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/package.json) enforces `engine-strict`.

**Workspace Synchronization**

When adding new packages to the monorepo, you must update both [`pnpm-workspace.yaml`](https://github.com/MoonshotAI/kimi-code/blob/main/pnpm-workspace.yaml) and `flake.nix`. The latter is manually maintained and must stay synchronized with the workspace declaration, as documented in the "Monorepo Workspace Maintenance" section of [`AGENTS.md`](https://github.com/MoonshotAI/kimi-code/blob/main/AGENTS.md).

**Windows Shell Configuration**

The CLI expects a Bash environment. If you have installed Git for Windows but Bash resides outside the default path, set the `KIMI_SHELL_PATH` environment variable to the absolute path of the Bash binary before running development commands.

## Summary

- **Install Node.js ≥24.15.0 and pnpm 10.33.0** before cloning, as enforced by [`package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/package.json) engine constraints.
- **Run `pnpm install`** to populate workspace dependencies and execute `scripts/fix-node-pty-perms.mjs`.
- **Use `pnpm dev:cli`** for terminal-based development or **`pnpm dev:web`** for the Vue 3 interface.
- **Synchronize [`pnpm-workspace.yaml`](https://github.com/MoonshotAI/kimi-code/blob/main/pnpm-workspace.yaml) and `flake.nix`** when modifying workspace packages to maintain build integrity.
- **Set `KIMI_SHELL_PATH` on Windows** if Bash is installed in a non-standard location to ensure the CLI functions correctly.

## Frequently Asked Questions

### What Node.js version is required to develop Kimi Code?

Kimi Code requires **Node.js ≥24.15.0** for development. The root [`package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/package.json) enforces this via `engine-strict`, and `pnpm install` will abort if your version is older. Use a version manager to switch to the correct runtime before setting up the development environment.

### Can I run Kimi Code on Windows?

Yes, but Windows requires additional configuration. Install Git for Windows to provide a Bash environment for the CLI. If Bash is not in the default location, set the `KIMI_SHELL_PATH` environment variable to its absolute path. Alternatively, Windows users can run the binary installer ([`install.sh`](https://github.com/MoonshotAI/kimi-code/blob/main/install.sh)) for quick testing without setting up the full Node.js toolchain.

### How do I add a new package to the Kimi Code monorepo?

When adding a package, update **[`pnpm-workspace.yaml`](https://github.com/MoonshotAI/kimi-code/blob/main/pnpm-workspace.yaml)** to include the new path, then manually synchronize **`flake.nix`** to reflect the same workspace structure. The [`AGENTS.md`](https://github.com/MoonshotAI/kimi-code/blob/main/AGENTS.md) file contains the definitive project map and workspace maintenance rules that govern these modifications.

### What is the difference between `pnpm dev:cli` and `pnpm dev:server`?

The **`pnpm dev:cli`** command launches the interactive terminal UI (`apps/kimi-code`) with an integrated agent session, while **`pnpm dev:server`** (or `pnpm dev:kap-server`) starts only the `kap-server` backend (`packages/kap-server`) without any front-end interface. Use the server-only mode when developing backend APIs or when connecting a separate client to the REST/WebSocket endpoints.