# How to Contribute to the Kimi-CLI Project: A Complete Developer's Guide

> Learn how to contribute to the Kimi-CLI project. Follow our guide to fork, set up, format commits, and submit pull requests to the MoonshotAI/kimi-cli repository.

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

---

**To contribute to the kimi-cli project, fork the repository, run `make prepare` to install dependencies and git hooks, follow conventional commit formatting, and submit a PR after verifying all checks pass via `make check` and `make test`.**

Contributing to MoonshotAI's kimi-cli requires navigating a Python-based monorepo with multiple workspace packages and a sophisticated terminal AI architecture. This guide covers the complete workflow from initial setup through submission, referencing the actual source structure in `src/kimi_cli/` and build automation defined in the `Makefile`.

## Setting Up Your Development Environment

Begin by cloning the repository and initializing the development toolchain. The project uses **uv** for dependency management and **prek** for git hooks.

```bash

# Clone your fork and enter the directory

git clone https://github.com/YOUR_USERNAME/kimi-cli.git
cd kimi-cli

# Install dependencies, sync workspaces, and install formatting hooks

make prepare

```

The `make prepare` target executes `uv sync` across all workspace packages (`kimi-cli`, `kosong`, `kaos`, `kimi-sdk`) and installs the **prek** hooks referenced in [`CONTRIBUTING.md`](https://github.com/MoonshotAI/kimi-cli/blob/main/CONTRIBUTING.md) (lines 10-21). This ensures ruff formatting and conventional commit validation run automatically on every commit.

## Understanding the Core Architecture

Before modifying code, understand the three-layer architecture: the CLI entry point, the runtime soul, and the extensible toolset.

### Entry Point and CLI Creation

The application starts in [`src/kimi_cli/cli/__init__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__init__.py), which invokes `KimiCLI.create()` in **[[`src/kimi_cli/app.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/app.py)](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/app.py)**. This factory method orchestrates several critical subsystems:

- **`load_config()`** in [`src/kimi_cli/config.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/config.py) reads `~/.kimi/config.toml` or CLI-specified config files
- **`OAuthManager`** in [`src/kimi_cli/auth/oauth.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/auth/oauth.py) handles Kimi Code token refresh
- **`Runtime.create()`** (lines 58-68) initializes the execution environment, loading plugins and tools
- **`load_agent()`** (lines 94-101) reads the default agent specification from `agentspec.DEFAULT_AGENT_FILE`
- **Context restoration** (lines 105-108) reloads prior conversation history from the session's `context_file`

### The Runtime and Soul System

The execution engine consists of two tightly coupled components. The **Runtime** class in [`src/kimi_cli/soul/agent.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/agent.py) orchestrates the LLM, toolset, session state, and sub-agent store. It feeds into **KimiSoul** in [`src/kimi_cli/soul/kimisoul.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/kimisoul.py), which contains the main loop processing user input, invoking the LLM, handling tool approvals, and streaming `WireMessage` objects via the abstraction layer in `src/kimi_cli/wire/`.

### Tool Registration and Extensibility

All built-in tools reside under `src/kimi_cli/tools/` (e.g., `shell/`, `file/`, `agent/`). The `Toolset` class in [`src/kimi_cli/soul/toolset.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/toolset.py) dynamically loads tools based on YAML agent specifications in `src/kimi_cli/agents/`.

To add a new tool:

1. Create a subclass of `BaseTool` in `src/kimi_cli/tools/<name>/`

```python

# src/kimi_cli/tools/mytool/mytool.py

from kimi_cli.tools.base import BaseTool

class MyTool(BaseTool):
    name = "mytool"
    description = "Performs custom operations."

    async def run(self, args: list[str]) -> str:
        return "execution result"

```

2. Register the tool in an agent spec YAML:

```yaml
tools:
  - import_path: "kimi_cli.tools.mytool"

```

## Following Code Quality Standards

The project enforces strict standards via the `Makefile`. Run these commands before submitting:

```bash

# Auto-format all Python code with ruff

make format

# Run linting (ruff), type checking (pyright), and non-blocking analysis (ty)

make check

```

All commits must follow the **conventional commit** format (e.g., `feat(tools): add MyTool for X functionality`). The prek hooks installed via `make prepare` validate this format automatically.

## Submitting a Pull Request

The contribution workflow requires specific steps defined in [`CONTRIBUTING.md`](https://github.com/MoonshotAI/kimi-cli/blob/main/CONTRIBUTING.md):

1. **Discuss large changes**: If your PR exceeds 100 lines of code, open an issue first to discuss architectural alignment
2. **Test coverage**: Add or update tests in `tests/` (unit) or `tests_e2e/` (integration)
3. **Full verification**: Ensure `make test` passes for all workspace packages
4. **Commit format**: Use prefixes like `feat:`, `fix:`, `refactor:`, or `docs:`

```bash

# Example workflow

git checkout -b feature/new-tool

# ... implement changes ...

make format
make check
make test
git commit -m "feat(tools): add batch processing tool"
git push origin feature/new-tool

```

The CI pipeline replicates the `Makefile` targets. PRs must pass all checks before merging.

## Summary

- **Setup**: Run `make prepare` to install `uv` dependencies and `prek` git hooks
- **Architecture**: Modify `src/kimi_cli/soul/` for runtime changes, `src/kimi_cli/tools/` for new capabilities, and [`src/kimi_cli/app.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/app.py) for CLI behavior
- **Quality**: Enforce ruff formatting and pyright type checking via `make check`
- **Process**: Use conventional commits, open issues for >100 line changes, and ensure `make test` passes

## Frequently Asked Questions

### Do I need to use uv specifically, or can I use pip?

You must use **uv** as specified in the `Makefile`. The build pipeline relies on `uv sync` to manage the monorepo workspace packages consistently across `kimi-cli`, `kosong`, `kaos`, and `kimi-sdk`. While pip might install dependencies, it will not handle the workspace isolation required for the build and test targets.

### Where do I add tests for my new tool?

Add unit tests in the `tests/` directory following the existing pytest structure. For integration testing, use `tests_e2e/`. Run specific test suites via `make test-kimi-cli` or the full suite with `make test`. The project uses pytest for all validation.

### What happens if I don't follow conventional commit format?

The **prek** git hooks installed by `make prepare` will reject commits that don't match the conventional commit pattern (e.g., `type(scope): description`). This enforcement ensures the changelog and versioning automation work correctly. Fix the message format and commit again.

### Can I contribute to the core Runtime or Soul components?

Yes, but changes to [`src/kimi_cli/soul/agent.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/agent.py) (Runtime) or [`src/kimi_cli/soul/kimisoul.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/soul/kimisoul.py) (Soul) affect the critical path. Before submitting PRs modifying these files—especially those involving the LLM interaction loop or Wire protocol—open an issue to discuss the architectural impact, even if the change is small.