# How to Contribute to Kimi Code: A Complete Guide for Open-Source Contributors

> Learn how to contribute to Kimi Code, an open-source project. This guide covers prerequisites like Node.js and pnpm, plus understanding its TypeScript monorepo structure for successful contributions.

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

---

**Contributing to Kimi Code requires Node.js ≥24.15.0, pnpm 10.33.0, and familiarity with its TypeScript monorepo structure organized into applications, core packages, and a public SDK.**

Kimi Code is the open-source TypeScript monorepo behind the **Kimi Code CLI/TUI**, web interface, and agent engine. Understanding how its packages interact helps contributors place changes correctly and submit high-quality pull requests. This guide walks through the repository architecture, development workflow, and best practices for contributing to the MoonshotAI/kimi-code project.

## Kimi Code Repository Architecture

The monorepo is organized into distinct layers, each with specific responsibilities and entry points. Knowing this structure helps you locate the right place for your contribution.

### Applications Layer (`apps/`)

Four applications sit at the top of the stack:

- **`apps/kimi-code`** – The command-line interface and terminal UI. Entry point is [[`apps/kimi-code/src/main.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/src/main.ts)](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/src/main.ts), which parses commands and launches the TUI.
- **`apps/kimi-web`** – Browser UI built with Vue 3 and Vite.
- **`apps/kimi-inspect`** – Web inspector for debugging sessions.
- **`apps/vis`** – Visual debugging tools.

### Core Packages Layer (`packages/`)

These packages contain the engine that powers all applications:

| Package | Purpose | Key Location |
|---------|---------|--------------|
| **`packages/agent-core`** | Unified agent engine: agents, sessions, services, skills, and tools | [[`packages/agent-core/src/agent.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/agent.ts)](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/agent.ts) |
| **`packages/kosong`** | LLM/provider abstraction layer |
| **`packages/kaos`** | Execution environment with file and process abstractions |
| **`packages/oauth`** | OAuth and authentication utilities |
| **`packages/telemetry`** | Client-side telemetry collection |
| **`packages/transcript`** | Transcript contract and storage layer |

### Public SDK (`packages/node-sdk`)

The [`packages/node-sdk`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/node-sdk) package exports **`@moonshot-ai/kimi-code-sdk`**, the official TypeScript SDK used by downstream projects. Entry point is [[`packages/node-sdk/src/index.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/node-sdk/src/index.ts)](https://github.com/MoonshotAI/kimi-code/blob/main/packages/node-sdk/src/index.ts).

### Server Package (`packages/kap-server`)

Runs the Kimi Code backend, exposing **REST + WebSocket APIs** at `/api/v1`. It wires the dependency-injection-based engine and supplies the transcript service.

### Documentation (`docs/`)

VitePress-powered documentation site. Edit these Markdown files when your change affects user-visible behavior.

### Workspace Management

Two files must stay synchronized when adding or removing packages:

- [[`pnpm-workspace.yaml`](https://github.com/MoonshotAI/kimi-code/blob/main/pnpm-workspace.yaml)](https://github.com/MoonshotAI/kimi-code/blob/main/pnpm-workspace.yaml) – pnpm workspace definition
- [`flake.nix`](https://github.com/MoonshotAI/kimi-code/blob/main/flake.nix) – Nix workspace definition

## Development Environment Setup

Before you contribute to Kimi Code, ensure your environment meets the requirements enforced in [`package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/package.json) and `.npmrc`.

### Prerequisites

- **Node.js ≥ 24.15.0**
- **pnpm 10.33.0**

### Fork and Clone

```bash
git clone https://github.com/<YOUR_USERNAME>/kimi-code.git
cd kimi-code

```

### Install Dependencies

```bash
pnpm install

```

## Running and Testing Changes

### Development Mode

Start the CLI with hot-reload to test interactively:

```bash
pnpm dev:cli

```

This opens the TUI. Try `/login` followed by your new commands.

### Testing

All packages use **Vitest**. Run the full suite to prevent regressions:

```bash
pnpm test

```

### Linting and Type Checking

The project uses **`oxlint`** for fast linting and TypeScript for type safety:

```bash
pnpm lint          # check only

pnpm lint:fix      # auto-fix issues

pnpm typecheck     # compile all packages

```

### Production Build

Compile every package including the web UI:

```bash
pnpm build

```

## Submitting Your Contribution

### Create a Changeset

Every pull request that touches release artifacts must include a changeset:

```bash
pnpm changeset

```

Follow the interactive prompts to select affected packages and choose the appropriate bump level (patch, minor, or major).

### Commit Format

Use **Conventional Commits** for your PR title and commit messages:

```

feat(agent-core): add new tool
fix(kimi-code): resolve TUI rendering issue
docs: update API reference

```

### Pull Request Checklist

CI enforces these automatically. Run them locally first:

```bash
pnpm lint
pnpm typecheck
pnpm test

```

Then push and open a PR using the provided template.

## Complete Contribution Workflow Example

```bash

# 1. Clone and install

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

# 2. Develop a new sub-agent

cd packages/agent-core/src/agents

# Create my-agent.ts with your implementation...

# 3. Test interactively

pnpm dev:cli   # Opens TUI; verify with /login then your command

# 4. Add unit tests

cd packages/agent-core/test
cat >> my-agent.test.ts <<'EOF'
import { expect, test } from 'vitest'
import { MyAgent } from '../src/agents/my-agent'

test('my agent does something', async () => {
  const result = await MyAgent.run('hello')
  expect(result).toContain('world')
})
EOF

# 5. Validate everything

pnpm lint
pnpm typecheck
pnpm test

# 6. Prepare for submission

pnpm changeset   # Select packages and bump level

git add .
git commit -m "feat(agent-core): add MyAgent"
git push origin HEAD

# Open PR on GitHub

```

## Contribution Best Practices

- **Discuss first** – Open an issue for feature proposals or large refactors before writing code.
- **Scope your PR** – Keep changes focused; avoid unrelated modifications exceeding 100 lines.
- **Follow existing patterns** – Match TypeScript style, `oxlint` rules, and code conventions in surrounding files.
- **Update documentation** – Edit `docs/` when behavior changes affect users.
- **Add tests** – Prefer extending existing test files rather than creating new ones.

## Key Reference Files

| File | Purpose |
|------|---------|
| [[`README.md`](https://github.com/MoonshotAI/kimi-code/blob/main/README.md)](https://github.com/MoonshotAI/kimi-code/blob/main/README.md) | Overview, quick-start, and install instructions |
| [[`CONTRIBUTING.md`](https://github.com/MoonshotAI/kimi-code/blob/main/CONTRIBUTING.md)](https://github.com/MoonshotAI/kimi-code/blob/main/CONTRIBUTING.md) | Full contribution guide and commit conventions |
| [[`AGENTS.md`](https://github.com/MoonshotAI/kimi-code/blob/main/AGENTS.md)](https://github.com/MoonshotAI/kimi-code/blob/main/AGENTS.md) | Project map, constraints, and workspace layout |

## Summary

- **Kimi Code** is a TypeScript monorepo with applications in `apps/`, core logic in `packages/`, and documentation in `docs/`
- **System requirements**: Node.js ≥24.15.0 and pnpm 10.33.0
- **Development cycle**: `pnpm dev:cli` for testing, `pnpm lint`/`pnpm typecheck`/`pnpm test` for validation
- **Required for PRs**: changeset (`pnpm changeset`), Conventional Commit format, and passing CI

## Frequently Asked Questions

### What is the fastest way to test changes in Kimi Code?

Run `pnpm dev:cli` to start the CLI in development mode with hot-reload. This builds the workspace and opens the TUI immediately, allowing you to interactively verify your changes without full production builds.

### Where should I add a new agent or tool in the Kimi Code repository?

Create new agents in `packages/agent-core/src/agents/` following the pattern in [[`packages/agent-core/src/agent.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/agent.ts)](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/agent.ts). Add corresponding tests in `packages/agent-core/test/`. The agent-core package is the unified engine for all agent functionality.

### What happens if I add a package but forget to update `flake.nix`?

The Nix-based development environment will break for contributors using Nix. Both [`pnpm-workspace.yaml`](https://github.com/MoonshotAI/kimi-code/blob/main/pnpm-workspace.yaml) and `flake.nix` must list the same packages. CI does not currently enforce this synchronization, so manual verification is required.

### Does Kimi Code require specific Git commit message formats?

Yes. All PR titles must follow **Conventional Commits** format: `type(scope): description`. Common types include `feat`, `fix`, `docs`, `refactor`, and `test`. The `scope` should match the affected package or application name.