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

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, 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 lines 63-65)
• pnpm 10.33.0 (specified in the packageManager field of 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)

On macOS or Linux, you can use the binary installer (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. 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.
• 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.
• 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 (the definitive project map and coding conventions), 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

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.

pnpm install

3. Launch Development Servers

Choose the component you want to run:

CLI/TUI (most common entry point):

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:

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

Server Only (for backend development):

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:

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:

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:

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 enforces engine-strict.

Workspace Synchronization

When adding new packages to the monorepo, you must update both 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.

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 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 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 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) 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 to include the new path, then manually synchronize flake.nix to reflect the same workspace structure. The 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.

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