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

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 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 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 and .npmrc)
• pnpm 10.33.0 (strictly pinned)

Installation Steps

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

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

Install dependencies across the monorepo:

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:

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:

pnpm test

Linting and Type Checking

The repository enforces code quality through automated checks:

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:

pnpm build

Creating a Changeset

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

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:

# 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	Complete contribution guide and workflow details
AGENTS.md	Project map, hard constraints, and workspace layout documentation
packages/agent-core/src/agent.ts	Core Agent class and entry point for all agents
packages/node-sdk/src/index.ts	Public SDK entry point exporting @moonshot-ai/kimi-code-sdk
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 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 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 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 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.

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