How to Contribute to Kimi-Code: A Complete Guide for Developers

Contribute to Kimi-Code by cloning the pnpm workspace, running pnpm install, and following the Conventional Commits workflow with mandatory changesets for all PRs.

Kimi-Code is MoonshotAI's TypeScript monorepo powering a CLI/TUI debugging suite and full-stack agent engine. This guide walks you through the exact steps needed to contribute code, open PRs, and navigate the repository structure based on the official source code.

Understanding the Kimi-Code Monorepo Structure

Kimi-Code organizes code into pnpm workspace packages, each encapsulating a distinct architectural concern:

Package	Path	Purpose
CLI / TUI	apps/kimi-code	User-facing command-line interface consuming the public SDK
Visual Debugger	apps/vis	Session replay and debugging UI
Public SDK	packages/node-sdk	Published @moonshot-ai/kimi-code-sdk package
Agent Core v1	packages/agent-core	Core agent abstractions and service layer
Agent Core v2	packages/agent-core-v2	Scoped DI engine (App → Workspace → Session → Agent)
LLM Provider Layer	packages/kosong	Provider-agnostic LLM abstraction
Execution Environment	packages/kaos	File-system and process utilities
Kap-Server	packages/kap-server	HTTP/WebSocket API exposing sessions
Client SDK	packages/klient	Contract-driven façade over the v2 engine
Tree-Sitter Bash	packages/tree-sitter-bash	Pure-TS bash parser without WASM
MiniDB	packages/minidb	Embedded JSON document store with full-text indexing

Reference AGENTS.md for the complete repository map and hard constraints.

Development Setup: Clone and Build Kimi-Code

Start contributing with these exact commands:

git clone https://github.com/MoonshotAI/kimi-code.git
cd kimi-code
pnpm install            # requires Node ≥ 24.15.0 & pnpm 10.33.0

Run the CLI in development mode for UI tweaks:

pnpm dev:cli

Execute the full test suite (all packages use Vitest):

pnpm test

Type-check and lint before committing:

pnpm typecheck   # builds packages first, then runs tsc

pnpm lint        # oxlint based lint

pnpm lint:fix    # auto-fixes format issues

Build the entire monorepo:

pnpm build

These scripts are defined in the root package.json and documented in CONTRIBUTING.md.

Kimi-Code Contribution Workflow

Step 1: Open an Issue First

Any change that modifies public behavior, adds a feature, or exceeds ~100 lines of refactor requires upfront discussion. See the "Before You Start" section in CONTRIBUTING.md.

Step 2: Create a Feature Branch

git checkout -b feat/your-description

Step 3: Follow Conventional Commits

All commits and PR titles must follow Conventional Commits format:

feat(agent-core): add tool deduplication
fix(kap-server): resolve WebSocket reconnect race
docs: update API examples

The CI enforces this via the pr-title-checker workflow. Reference the "Commit Convention" table in CONTRIBUTING.md for the full type list.

Step 4: Add a Changeset

Every PR affecting releases requires a changeset:

pnpm changeset

Follow the prompts to generate markdown under .changeset/. The repository uses the changesets tool for versioning—see .changeset/README.md for details.

Step 5: Open Your PR

• Use the PR template
• Link the related issue
• Ensure the title complies with Conventional Commits

CI automatically runs lint, type-check, and tests. Update docs in docs/ (VitePress site) for public API or UI changes.

Key Source Files for Contributors

Component	Critical Files
CLI/TUI	apps/kimi-code/src/main.ts, apps/kimi-code/src/ui/*.tsx
SDK Entry	packages/node-sdk/src/index.ts
Agent v1 Core	packages/agent-core/src/Agent.ts, packages/agent-core/src/services/*
Agent v2 Engine	packages/agent-core-v2/src/app/scopes.ts, packages/agent-core-v2/src/features/*
Kap-Server API	packages/kap-server/src/server.ts, packages/kap-server/src/api/v1/*.ts
Klient Client	packages/klient/src/index.ts
Bash Parser	packages/tree-sitter-bash/src/parser.ts
MiniDB Store	packages/minidb/src/MiniDb.ts

Each package contains its own AGENTS.md describing local conventions. The root AGENTS.md provides the overarching architectural map.

Code Examples for Common Contributions

Adding a New Agent Skill (v2 Engine)

Create a skill in packages/agent-core-v2/src/skills/my-skill.ts:

import { ITool, ToolResult } from '#/tools';
import { registerSkill } from '#/skillRegistry';

export const mySkill = registerSkill('my-skill', async (input: string): Promise<ToolResult> => {
  // simple echo tool
  return { output: `You said: ${input}` };
});

Add corresponding tests in packages/agent-core-v2/test/my-skill.test.ts, then run pnpm test and generate a changeset.

Exposing a Skill via CLI Command

Add to apps/kimi-code/src/commands/hello.ts:

import { Command } from 'commander';
import { mySkill } from '#/skills/my-skill';

export const helloCmd = new Command('hello')
  .description('Say hello via the new skill')
  .argument('<name>', 'Name to greet')
  .action(async (name) => {
    const result = await mySkill(`hello ${name}`);
    console.log(result.output);
  });

Register the command in apps/kimi-code/src/main.ts and restart pnpm dev:cli.

Running the Server Locally

pnpm dev:server   # launches kap-server with hot reload

Interact via the SDK or TUI at the running endpoint.

Critical Files Every Contributor Must Know

File	Purpose
README.md	Project overview and quick-start
CONTRIBUTING.md	Full contributor guide, dev scripts, commit policy
AGENTS.md	Repository-level map and workflow requirements
pnpm-workspace.yaml	Workspace package declarations
flake.nix	Nix build definition (must sync with workspace)
package.json	Central scripts and engine constraints
scripts/check-nix-workspace.mjs	Lint ensuring flake.nix matches workspace
/.github/workflows/ci.yml	CI pipeline (lint, type-check, test)

Summary

• Kimi-Code contribution starts with the pnpm workspace setup and Node ≥ 24.15.0
• Conventional Commits are mandatory for all commits and PR titles
• Changesets (pnpm changeset) are required for any release-affecting PR
• Issue-first workflow: Discuss changes >100 lines or affecting public behavior before coding
• Monorepo discipline: New packages must appear in both pnpm-workspace.yaml and flake.nix
• Quality gates: Run pnpm lint, pnpm typecheck, and pnpm test locally before PR submission
• Documentation: Update docs/ for any user-visible changes

Frequently Asked Questions

What Node.js version does Kimi-Code require?

Kimi-Code requires Node ≥ 24.15.0 and pnpm 10.33.0 exactly. These constraints are enforced in the root package.json engines field and validated by CI.

Do I need a changeset for documentation-only PRs?

No. Changesets are only required for PRs that modify code, behavior, or public APIs. Pure documentation updates in docs/ or README files do not need pnpm changeset, but they still require Conventional Commit formatting (use docs: prefix).

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

Create your package directory, then register it in both pnpm-workspace.yaml and flake.nix. The CI runs scripts/check-nix-workspace.mjs to verify these files stay synchronized. Reference existing packages like packages/minidb for the standard package.json structure.

Where should I implement a new agent capability?

Use Agent Core v2 for new features. The v2 engine in packages/agent-core-v2 provides scoped dependency injection (App → Workspace → Session → Agent) and is the active development path. Place skills in packages/agent-core-v2/src/skills/ and features in packages/agent-core-v2/src/features/.

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