# How to Contribute to the Kimi Code Project: A Complete Developer Guide

> Learn how to contribute to the kimi code project. Follow our step by step guide to fork the repository, set up your environment, develop features, and submit pull requests.

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

---

**To contribute to kimi-code, fork the MoonshotAI/kimi-code repository, install Node ≥24.15.0 and pnpm 10.33.0, run `pnpm install`, develop features using `pnpm dev:cli`, validate with `pnpm lint` and `pnpm test`, and submit pull requests with changesets following Conventional Commits.**

Contributing to the **kimi-code** project requires understanding its TypeScript monorepo structure, which powers the CLI/TUI, web interfaces, and the underlying agent engine. Whether you are fixing bugs in the core agent logic or adding features to the Vue-based web UI, following the established workflow ensures your changes integrate smoothly. This guide covers the architecture, development setup, and submission process based on the actual source code structure.

## Understanding the Kimi Code Architecture

The repository organizes code into distinct layers, each with specific responsibilities. Knowing where components live prevents breaking changes and helps you locate the right entry points for modifications.

### Applications Layer

The `apps/` directory contains the user-facing executables and interfaces:

- **`apps/kimi-code`** — The command-line interface and terminal UI (TUI)
- **`apps/kimi-web`** — Browser-based interface built with Vue 3 and Vite
- **`apps/kimi-inspect`** — Web inspector for debugging agent sessions
- **`apps/vis`** — Visual debugging utilities

### Core Packages

Business logic resides in `packages/`, the heart of the agent engine:

- **`packages/agent-core`** — Unified agent engine managing agents, sessions, services, skills, and tools
- **`packages/kosong`** — LLM and provider abstraction layer
- **`packages/kaos`** — Execution environment with file and process abstractions
- **`packages/oauth`** — Authentication and OAuth utilities
- **`packages/telemetry`** — Client-side telemetry collection
- **`packages/transcript`** — Transcript contracts and storage layer

### Public SDK and Server

- **`packages/node-sdk`** — Exports `@moonshot-ai/kimi-code-sdk`, the public TypeScript SDK for downstream projects
- **`packages/kap-server`** — Backend server running REST and WebSocket APIs (`/api/v1`), wiring the DI-based engine and transcript service

### Documentation and Workspace Management

The VitePress documentation site lives in `docs/`. The monorepo uses [`pnpm-workspace.yaml`](https://github.com/MoonshotAI/kimi-code/blob/main/pnpm-workspace.yaml) for package management, with a parallel `flake.nix` defining the Nix workspace. **Critical:** Any package added or removed must be reflected in both [`pnpm-workspace.yaml`](https://github.com/MoonshotAI/kimi-code/blob/main/pnpm-workspace.yaml) and `flake.nix` to maintain workspace consistency.

## Setting Up Your Development Environment

Before writing code, ensure your local environment matches the project's strict toolchain requirements.

### Prerequisites

- **Node.js** ≥24.15.0 (enforced in [`package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/package.json) and `.npmrc`)
- **pnpm** 10.33.0 (strictly pinned)

### Installation Steps

Fork the repository on GitHub, then clone your fork locally:

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

```

Install dependencies across the monorepo:

```bash
pnpm install

```

## Development Workflow

The project uses a standardized workflow to ensure code quality and consistency across the TypeScript packages.

### Running the CLI in Development Mode

Start the TUI with hot-reload to test changes interactively:

```bash
pnpm dev:cli

```

This builds the workspace and launches the terminal interface. Use `/login` within the TUI to authenticate before testing agent commands.

### Testing with Vitest

All packages use Vitest for unit testing. Run the complete suite to verify nothing breaks:

```bash
pnpm test

```

### Linting and Type Checking

The repository enforces code quality through automated checks:

```bash
pnpm lint          # Check for issues with oxlint

pnpm lint:fix      # Auto-fix where possible

pnpm typecheck     # Compile all packages for type safety

```

### Building for Production

Compile every package, including the web UI, to verify production builds succeed:

```bash
pnpm build

```

### Creating a Changeset

Every pull request that modifies release artifacts must include a changeset. This documents version bumps and generates changelogs:

```bash
pnpm changeset

```

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

### Submitting Your Contribution

Open a pull request using the provided template. Format your PR title using **Conventional Commits** (e.g., `feat(agent-core): add new tool`). CI automatically enforces linting, type-checking, and tests.

## Contribution Guidelines

Following these standards accelerates review and prevents常见 issues.

### Pre-Development Checklist

- **Discuss first** — Open an issue for feature proposals or large refactors before coding
- **Scope the change** — Keep pull requests focused; avoid mixing unrelated changes exceeding 100 lines
- **Follow the style guide** — Adhere to TypeScript patterns, `oxlint` rules, and existing code conventions

### Code Quality Requirements

- **Update documentation** — If your change alters user-visible behavior, edit the relevant pages under `docs/`
- **Add tests** — Prefer adding tests to existing test files for affected modules rather than creating new test directories
- **Run CI locally** — Ensure `pnpm lint`, `pnpm typecheck`, and `pnpm test` all pass before pushing

## Example Contribution Walkthrough

Here is a complete workflow for adding a new agent to the core package:

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

# 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 processes input correctly', async () => {
  const result = await MyAgent.run('hello')
  expect(result).toContain('world')
})
EOF

# 5. Validate code quality

pnpm lint
pnpm typecheck
pnpm test

# 6. Prepare for submission

pnpm changeset
git add .
git commit -m "feat(agent-core): add MyAgent for specialized task handling"
git push origin HEAD

# Open PR on GitHub

```

## Key Files and Entry Points

Understanding these critical files helps you navigate the codebase effectively:

| File | Purpose |
|------|---------|
| [`CONTRIBUTING.md`](https://github.com/MoonshotAI/kimi-code/blob/main/CONTRIBUTING.md) | Complete contribution guide and workflow details |
| [`AGENTS.md`](https://github.com/MoonshotAI/kimi-code/blob/main/AGENTS.md) | Project map, hard constraints, and workspace layout documentation |
| [`packages/agent-core/src/agent.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/agent-core/src/agent.ts) | Core `Agent` class and entry point for all agents |
| [`packages/node-sdk/src/index.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/packages/node-sdk/src/index.ts) | Public SDK entry point exporting `@moonshot-ai/kimi-code-sdk` |
| [`apps/kimi-code/src/main.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/apps/kimi-code/src/main.ts) | CLI bootstrap that parses commands and launches the TUI |

## Summary

- **kimi-code** is a TypeScript monorepo requiring Node ≥24.15.0 and pnpm 10.33.0, managed through [`pnpm-workspace.yaml`](https://github.com/MoonshotAI/kimi-code/blob/main/pnpm-workspace.yaml) and `flake.nix`
- The architecture separates applications (`apps/`), core logic (`packages/`), SDK (`packages/node-sdk`), and server (`packages/kap-server`)
- Use `pnpm dev:cli` for interactive development, `pnpm test` for Vitest validation, and `pnpm changeset` for versioning
- All contributions must pass `oxlint` and TypeScript type-checking, follow Conventional Commits, and include changesets for release-bound changes
- Synchronize [`pnpm-workspace.yaml`](https://github.com/MoonshotAI/kimi-code/blob/main/pnpm-workspace.yaml) and `flake.nix` whenever modifying workspace packages

## Frequently Asked Questions

### What are the specific system requirements for contributing to kimi-code?

You must use **Node.js version 24.15.0 or higher** and **pnpm version 10.33.0 exactly**, as enforced by [`package.json`](https://github.com/MoonshotAI/kimi-code/blob/main/package.json) and `.npmrc` configurations. These versions ensure compatibility with the monorepo's build scripts and dependency resolution.

### How do I add a new package to the kimi-code monorepo?

Create your package directory under `packages/` or `apps/`, then add the path to both [`pnpm-workspace.yaml`](https://github.com/MoonshotAI/kimi-code/blob/main/pnpm-workspace.yaml) and `flake.nix`. The Nix workspace definition must stay synchronized with the pnpm workspace; forgetting to update `flake.nix` will cause CI failures for contributors using Nix.

### Do I need to create a changeset for every pull request?

You only need a changeset (created via `pnpm changeset`) if your PR touches code that affects release artifacts. Documentation-only changes or internal refactors that do not alter public APIs typically do not require changesets, though the CI will prompt if one is necessary.

### How can I debug the agent engine during development?

Run `pnpm dev:cli` to launch the TUI with hot-reload, or use `apps/kimi-inspect` (the web inspector) to debug active sessions. For deeper debugging, the `apps/vis` package provides visual debugging tools to trace agent decisions and tool executions.