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

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.

# 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 (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, which invokes KimiCLI.create() in [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 reads ~/.kimi/config.toml or CLI-specified config files
• OAuthManager in 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 orchestrates the LLM, toolset, session state, and sub-agent store. It feeds into KimiSoul in 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 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>/

# 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:

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

Following Code Quality Standards

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

# 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:

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:

# 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 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 (Runtime) or 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.

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