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

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
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, runs an update pre-flight check in src/cli/update/preflight.ts, then dispatches to either the TUI (src/cli/run-shell.ts) or headless mode (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

# 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 defines workspace boundaries. Any new package you create must also be registered in flake.nix per the "Monorepo Workspace Maintenance" section of 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

# 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

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

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 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	Process entry, crash handlers, native module hooks, CLI dispatch
apps/kimi-code/src/cli/commands.ts	Commander.js definitions for run, migrate, upgrade
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	Canonical project map and workspace maintenance rules

Debugging and Testing

Run the full test suite after any changes:

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 and flake.nix per 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 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 installs crash handlers and native hooks, parses arguments via Commander.js in src/cli/commands.ts, runs update pre-flight checks from src/cli/update/preflight.ts, then dispatches to either the TUI (src/cli/run-shell.ts) or headless prompt mode (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 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.

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