# How to Get Started with Kimi-Code Development: A Complete Setup Guide

> Start Kimi-Code development with this guide. Set up Node.js, pnpm, and the monorepo, then launch the TUI or build custom skills with ease.

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

---

**Kimi-Code development requires Node.js ≥24.15, pnpm 10.33, and a clone of the MoonshotAI/kimi-code monorepo, after which you can run `pnpm dev:cli` to launch the interactive TUI or build custom skills in `~/.config/kimi-code/skills`.**

Kimi-Code is a TypeScript-based AI coding assistant developed by MoonshotAI. This guide walks you through the repository structure, build system, and first steps for contributing to or extending the codebase. Whether you want to debug the CLI, add a new skill, or integrate with the core agent engine, understanding the monorepo layout is essential for productive Kimi-Code development.

## Repository Structure and Architecture

Kimi-Code follows a **pnpm workspace monorepo** pattern with clear separation between applications and shared packages.

### Application Layer (`apps/`)

| Directory | Purpose | Key Entry Point |
|-----------|---------|---------------|
| `apps/kimi-code` | CLI binary and terminal UI | [`src/main.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/main.ts) |
| `apps/vis` | Session replay and visualization tools | `apps/vis/` |
| `apps/kimi-inspect` | Web inspector for debug RPC | `apps/kimi-inspect/` |

The CLI application in `apps/kimi-code` serves as the primary entry point. It parses arguments via Commander.js in [`src/cli/commands.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/cli/commands.ts), runs an update pre-flight check in [`src/cli/update/preflight.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/cli/update/preflight.ts), then dispatches to either the TUI ([`src/cli/run-shell.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/cli/run-shell.ts)) or headless mode ([`src/cli/run-prompt.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/cli/run-prompt.ts)).

### Core Packages (`packages/`)

| Package | Responsibility | Location |
|---------|---------------|----------|
| `agent-core-v2` | DI-scoped agent engine (App/Workspace/Session/Agent scopes) | `packages/agent-core-v2/src/` |
| `node-sdk` | Public SDK (`@moonshot-ai/kimi-code-sdk`) | `packages/node-sdk/src/` |
| `kosong` | LLM provider abstraction layer | `packages/kosong/src/` |
| `kaos` | File-system, process, and sandbox utilities | `packages/kaos/src/` |
| `kap-server` | HTTP/WebSocket API (`/api/v1`) | `packages/kap-server/src/` |
| `klient` | Editor RPC façade (`@moonshot-ai/klient`) | `packages/klient/src/` |
| `transcript` | Isomorphic turn transcript storage | `packages/transcript/src/` |
| `minidb` | Embedded JSON document store | `packages/minidb/src/` |
| `telemetry` | Client-side telemetry plumbing | `packages/telemetry/src/` |
| `oauth` | Kimi OAuth login flows | `packages/oauth/src/` |

The **agent engine** in `packages/agent-core-v2` handles all heavy lifting: planning, tool execution, and LLM orchestration. The CLI creates a harness via `createKimiHarness` from the public SDK, which wires together sessions, telemetry, and configuration.

## Initial Setup and Installation

### Prerequisites

- **Node.js** ≥ 24.15
- **pnpm** 10.33 ( enforced via `packageManager` field)
- Git

### Clone and Install

```bash

# Clone the repository

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

# Install all workspace dependencies

pnpm install

```

The [`pnpm-workspace.yaml`](https://github.com/MoonshotAI/kimi-code/blob/main/pnpm-workspace.yaml) defines workspace boundaries. Any new package you create must also be registered in `flake.nix` per the "Monorepo Workspace Maintenance" section of [`AGENTS.md`](https://github.com/MoonshotAI/kimi-code/blob/main/AGENTS.md).

## Development Workflow Commands

| Command | Purpose | Notes |
|---------|---------|-------|
| `pnpm dev:cli` | Start CLI in watch mode | Hot-reloads on source changes |
| `pnpm test` | Run full Vitest suite | Unit, integration, and e2e tests |
| `pnpm typecheck` | Strict TypeScript validation | `tsc --noEmit` |
| `pnpm build` | Production build | Outputs to `apps/kimi-code/dist/` |
| `pnpm lint` | Lint with oxlint | Type-aware checks enabled |

### Running in Development Mode

```bash

# Launch the interactive TUI with hot reload

pnpm dev:cli

```

Once running, try a built-in prompt:

```

> Take a look at this project and explain its main directories.

```

### Building Release Artifacts

```bash
pnpm build

```

This produces:
- The native CLI binary (with SEA workers for MiniDB text builder and search)
- Pre-built web UI bundle
- All package distributions

## Creating Custom Skills for Kimi-Code

Skills are self-contained modules implementing the `Skill` interface from `@moonshot-ai/kimi-code-sdk`. They auto-load from `~/.config/kimi-code/skills` or directories specified via `--skills-dirs`.

### Skill Directory Layout

```

~/.config/kimi-code/skills/
└── todo/
    ├── manifest.json
    └── index.ts

```

### Example: Todo List Skill

```bash
mkdir -p ~/.config/kimi-code/skills/todo

cat > ~/.config/kimi-code/skills/todo/manifest.json <<'EOF'
{
  "name": "todo",
  "description": "Manage a personal todo list",
  "entry": "index.ts"
}
EOF

cat > ~/.config/kimi-code/skills/todo/index.ts <<'EOF'
import { Skill } from '@moonshot-ai/kimi-code-sdk';

export const skill: Skill = {
  name: 'todo',
  description: 'Add, list or complete items',
  async run({ args }) {
    // Stub implementation—persist to file in production
    return `You asked for: ${args.join(' ')}`;
  },
};
EOF

```

Restart the CLI and type `/skills` to see your new skill in the picker. The marketplace UI surface is driven by [`src/utils/plugin-marketplace.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/utils/plugin-marketplace.ts) in the CLI package.

## Key Source Files for Deep Dives

Understanding these files accelerates Kimi-Code development:

| File | Role |
|------|------|
| [`apps/kimi-code/src/main.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/src/main.ts) | Process entry, crash handlers, native module hooks, CLI dispatch |
| [`apps/kimi-code/src/cli/commands.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/src/cli/commands.ts) | Commander.js definitions for `run`, `migrate`, `upgrade` |
| [`apps/kimi-code/src/tui/kimi-tui.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/src/tui/kimi-tui.ts) | Render loop and terminal event handling |
| `packages/agent-core-v2/src/` | Service container, scope lifecycle (`App` → `Workspace` → `Session` → `Agent`) |
| `packages/kosong/src/` | Provider adapters for OpenAI, Anthropic, and other LLM backends |
| `packages/minidb/src/` | Embedded search index and JSON document storage |
| [`AGENTS.md`](https://github.com/MoonshotAI/kimi-code/blob/main/AGENTS.md) | Canonical project map and workspace maintenance rules |

## Debugging and Testing

Run the full test suite after any changes:

```bash
pnpm test

```

For visual debugging, use the dedicated tools:
- **`apps/vis/`**: Replay and inspect agent sessions
- **`apps/kimi-inspect/`**: Web inspector for the server's debug RPC surface

## Summary

- **Kimi-Code is a pnpm monorepo** with clear boundaries between CLI entry point (`apps/kimi-code`), core engine (`packages/agent-core-v2`), and public SDK (`packages/node-sdk`).
- **Development requires Node.js ≥24.15 and pnpm 10.33**; use `pnpm dev:cli` for rapid iteration.
- **Skills extend functionality** via the `Skill` interface from `@moonshot-ai/kimi-code-sdk`, auto-discovered from `~/.config/kimi-code/skills`.
- **New packages must sync to both [`pnpm-workspace.yaml`](https://github.com/MoonshotAI/kimi-code/blob/main/pnpm-workspace.yaml) and `flake.nix`** per [`AGENTS.md`](https://github.com/MoonshotAI/kimi-code/blob/main/AGENTS.md) guidelines.
- **Release builds** produce native binaries with embedded SEA workers via `pnpm build`.

## Frequently Asked Questions

### What is the minimum Node.js version for Kimi-Code development?

Node.js 24.15 or later is required. The `packageManager` field in [`package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/package.json) enforces pnpm 10.33 to ensure consistent dependency resolution across the monorepo.

### How does the CLI boot process work?

The `main()` function in [`apps/kimi-code/src/main.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/src/main.ts) installs crash handlers and native hooks, parses arguments via Commander.js in [`src/cli/commands.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/cli/commands.ts), runs update pre-flight checks from [`src/cli/update/preflight.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/cli/update/preflight.ts), then dispatches to either the TUI ([`src/cli/run-shell.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/cli/run-shell.ts)) or headless prompt mode ([`src/cli/run-prompt.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/cli/run-prompt.ts)).

### Where does the actual AI agent logic live?

All agent execution, planning, and tool calling resides in `packages/agent-core-v2`. The CLI is a thin harness that creates sessions via `createKimiHarness` from the public SDK (`@moonshot-ai/kimi-code-sdk`), which wires telemetry, configuration, and LLM providers together.

### Can I extend Kimi-Code without modifying the core repository?

Yes. Create skills in `~/.config/kimi-code/skills/` or any directory passed to `--skills-dirs`. Each skill needs only a [`manifest.json`](https://github.com/MoonshotAI/kimi-code/blob/main/manifest.json) and an entry point exporting a `Skill` interface implementation. The CLI discovers and loads these at startup without requiring a rebuild of the core codebase.