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

> Learn how to contribute to Kimi-Code project. Clone the repo, install dependencies, and follow the Conventional Commits workflow with changesets for all PRs. Start contributing today!

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

---

**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](https://github.com/MoonshotAI/kimi-code/blob/main/AGENTS.md)** for the complete repository map and hard constraints.

## Development Setup: Clone and Build Kimi-Code

Start contributing with these exact commands:

```bash
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:

```bash
pnpm dev:cli

```

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

```bash
pnpm test

```

Type-check and lint before committing:

```bash
pnpm typecheck   # builds packages first, then runs tsc

pnpm lint        # oxlint based lint

pnpm lint:fix    # auto-fixes format issues

```

Build the entire monorepo:

```bash
pnpm build

```

These scripts are defined in the root [`package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/package.json) and documented in **[CONTRIBUTING.md](https://github.com/MoonshotAI/kimi-code/blob/main/CONTRIBUTING.md#development-setup)**.

## 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](https://github.com/MoonshotAI/kimi-code/blob/main/CONTRIBUTING.md)**.

### Step 2: Create a Feature Branch

```bash
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](https://github.com/MoonshotAI/kimi-code/blob/main/CONTRIBUTING.md#commit-convention)** for the full type list.

### Step 4: Add a Changeset

Every PR affecting releases requires a changeset:

```bash
pnpm changeset

```

Follow the prompts to generate markdown under `.changeset/`. The repository uses the **changesets** tool for versioning—see **[.changeset/README.md](https://github.com/MoonshotAI/kimi-code/blob/main/.changeset/README.md)** for details.

### Step 5: Open Your PR

- Use the **[PR template](https://github.com/MoonshotAI/kimi-code/blob/main/.github/pull_request_template.md)**
- 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`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/src/main.ts), `apps/kimi-code/src/ui/*.tsx` |
| **SDK Entry** | [`packages/node-sdk/src/index.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/node-sdk/src/index.ts) |
| **Agent v1 Core** | [`packages/agent-core/src/Agent.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/Agent.ts), `packages/agent-core/src/services/*` |
| **Agent v2 Engine** | [`packages/agent-core-v2/src/app/scopes.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/app/scopes.ts), `packages/agent-core-v2/src/features/*` |
| **Kap-Server API** | [`packages/kap-server/src/server.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/kap-server/src/server.ts), `packages/kap-server/src/api/v1/*.ts` |
| **Klient Client** | [`packages/klient/src/index.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/klient/src/index.ts) |
| **Bash Parser** | [`packages/tree-sitter-bash/src/parser.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/tree-sitter-bash/src/parser.ts) |
| **MiniDB Store** | [`packages/minidb/src/MiniDb.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/minidb/src/MiniDb.ts) |

Each package contains its own [`AGENTS.md`](https://github.com/MoonshotAI/kimi-code/blob/main/AGENTS.md) describing local conventions. The root **[AGENTS.md](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core-v2/src/skills/my-skill.ts):

```typescript
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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/src/commands/hello.ts):

```typescript
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`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/src/main.ts) and restart `pnpm dev:cli`.

### Running the Server Locally

```bash
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](https://github.com/MoonshotAI/kimi-code/blob/main/README.md)** | Project overview and quick-start |
| **[CONTRIBUTING.md](https://github.com/MoonshotAI/kimi-code/blob/main/CONTRIBUTING.md)** | Full contributor guide, dev scripts, commit policy |
| **[AGENTS.md](https://github.com/MoonshotAI/kimi-code/blob/main/AGENTS.md)** | Repository-level map and workflow requirements |
| **[pnpm-workspace.yaml](https://github.com/MoonshotAI/kimi-code/blob/main/pnpm-workspace.yaml)** | Workspace package declarations |
| **[flake.nix](https://github.com/MoonshotAI/kimi-code/blob/main/flake.nix)** | Nix build definition (must sync with workspace) |
| **[package.json](https://github.com/MoonshotAI/kimi-code/blob/main/package.json)** | Central scripts and engine constraints |
| **[scripts/check-nix-workspace.mjs](https://github.com/MoonshotAI/kimi-code/blob/main/scripts/check-nix-workspace.mjs)** | Lint ensuring `flake.nix` matches workspace |
| **[/.github/workflows/ci.yml](https://github.com/MoonshotAI/kimi-code/blob/main/.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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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`](https://github.com/MoonshotAI/kimi-code/blob/main/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/`.