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

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), 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)
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 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).

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) – pnpm workspace definition
• flake.nix – Nix workspace definition

Development Environment Setup

Before you contribute to Kimi Code, ensure your environment meets the requirements enforced in package.json and .npmrc.

Prerequisites

• Node.js ≥ 24.15.0
• pnpm 10.33.0

Fork and Clone

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

Install Dependencies

pnpm install

Running and Testing Changes

Development Mode

Start the CLI with hot-reload to test interactively:

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:

pnpm test

Linting and Type Checking

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

pnpm lint          # check only

pnpm lint:fix      # auto-fix issues

pnpm typecheck     # compile all packages

Production Build

Compile every package including the web UI:

pnpm build

Submitting Your Contribution

Create a Changeset

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

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:

pnpm lint
pnpm typecheck
pnpm test

Then push and open a PR using the provided template.

Complete Contribution Workflow Example

# 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)	Overview, quick-start, and install instructions
[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)	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). 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 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.

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