# How to Integrate kimi-cli with Existing Projects: A Complete Guide

> Learn how to integrate kimi-cli into your existing Python projects. Import KimiCLI and call create() to programmatically spawn an agent runtime without the command line. Get started today.

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

---

**You can integrate kimi-cli into any Python project by importing the `KimiCLI` class from [[`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) and calling `await KimiCLI.create()` to programmatically spawn an agent runtime without using the command line.**

The MoonshotAI/kimi-cli repository is architected as both a command-line interface and a reusable Python library. This dual nature allows developers to embed Kimi's agent runtime directly into existing applications, automation scripts, or web services, bypassing the terminal entirely while retaining full access to sessions, tools, and model configurations.

## Core Integration Architecture

### The KimiCLI Class

The primary integration point is the `KimiCLI` class defined 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 class encapsulates the entire agent lifecycle, including configuration loading, LLM initialization, and UI selection. It exposes multiple runtime modes through distinct methods:

- **`run_shell()`** – Launches the interactive terminal UI.
- **`run_print()`** – Executes in non-interactive mode, ideal for scripting.
- **`run_acp()`** – Runs the Agent Communication Protocol server.
- **`run_wire_stdio()`** – Enables custom wire protocol communication.

### Session Persistence and Configuration

Integration requires managing conversation state via the `Session` class in [[`src/kimi_cli/session.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/session.py)](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/session.py). Use `Session.create()` to initialize a new workspace or `Session.find()` to resume existing conversations. Configuration loading is handled by `load_config()`, which respects the same YAML settings used by the CLI entry point in [[`src/kimi_cli/cli/__init__.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__init__.py)](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/cli/__init__.py).

## Step-by-Step Integration Example

The following example demonstrates embedding kimi-cli in a standalone Python script:

```python
import asyncio
from kimi_cli.app import KimiCLI, enable_logging
from kimi_cli.session import Session
from kimi_cli.config import load_config

async def run_kimi():
    # Enable debug logging (optional)

    enable_logging(debug=True)
    
    # Initialize or resume a session

    work_dir = Session.default_work_dir()
    session = await Session.create(work_dir)
    
    # Create the CLI instance with custom parameters

    kimi = await KimiCLI.create(
        session,
        config=load_config(),
        model_name="gpt-4o-mini",
        yolo=True,              # Auto-approve tool calls

        ui_mode="print",        # Non-interactive mode

        skills_dirs=None,       # Add custom skill paths if needed

    )
    
    # Execute and capture output

    result = await kimi.run_print(
        input_format="text",
        output_format="text",
        prompt="Analyze the current project structure.",
        final_only=True,
    )
    
    print("Agent response:", result)

if __name__ == "__main__":
    asyncio.run(run_kimi())

```

Key implementation details:

- **`await KimiCLI.create(...)`** mirrors the CLI initialization logic, wiring together the LLM layer from [`packages/kosong`](https://github.com/MoonshotAI/kimi-cli/tree/main/packages/kosong), the toolset dispatcher, and configuration.
- Setting **`yolo=True`** disables interactive confirmations, enabling fully automated operation in CI pipelines or background jobs.
- The **`run_print`** method returns structured text output suitable for programmatic consumption without TUI overhead.

## Extending Integration Capabilities

### Custom Tool Integration

Extend the agent's capabilities by registering custom Python functions with the `KimiToolset` class in [[`src/kimi_cli/toolset.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/toolset.py)](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/toolset.py). The dispatcher loads built-in tools (file I/O, shell commands, web requests) and accepts additional tools via the `register_tool()` API, injecting them into the agent's context.

### Agent Specifications

Customize behavior by providing YAML agent specifications located in [`src/kimi_cli/agents/`](https://github.com/MoonshotAI/kimi-cli/tree/main/src/kimi_cli/agents) or via external files. These specs define system prompts, available sub-agents, and default toolsets that constrain or enhance the LLM's behavior.

### Official SDK Wrapper

For simpler integration, use the **`kimi-sdk`** package located in [`packages/kimi-sdk`](https://github.com/MoonshotAI/kimi-cli/tree/main/packages/kimi-sdk). This SDK provides synchronous wrappers around the async runtime, abstracting session management and configuration details for library consumers who prefer traditional blocking APIs.

## Remote and Distributed Workflows

For microservice architectures or remote execution, kimi-cli exposes an MCP (Multi-Channel Protocol) server implemented in [[`src/kimi_cli/mcp.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/mcp.py)](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/mcp.py). Existing projects can act as MCP clients, invoking Kimi agents over JSON-RPC channels without hosting the Python runtime locally.

## Summary

- Import **`KimiCLI`** from [[`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) to embed the full agent runtime in your project.
- Use **`await KimiCLI.create()`** with a `Session` object to initialize the environment programmatically.
- Select the appropriate UI mode: **`run_print()`** for automation, **`run_shell()`** for interactive use, or **`run_acp()`** for server deployments.
- Extend functionality by registering tools with **`KimiToolset`** in [[`src/kimi_cli/toolset.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/toolset.py)](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/toolset.py).
- Leverage the **`kimi-sdk`** package in [`packages/kimi-sdk`](https://github.com/MoonshotAI/kimi-cli/tree/main/packages/kimi-sdk) for simplified synchronous APIs.
- Deploy remotely using the MCP server in [[`src/kimi_cli/mcp.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/mcp.py)](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/mcp.py).

## Frequently Asked Questions

### Can I use kimi-cli in a synchronous Python script?

**Yes, but you must handle the async runtime.** The `KimiCLI` class uses `async/await` patterns throughout. Wrap your integration code in `asyncio.run()` or use the **`kimi-sdk`** package, which provides synchronous wrappers that handle the event loop internally.

### How do I add custom tools to the embedded runtime?

**Use the `KimiToolset` registration API.** After creating a `KimiCLI` instance, access its toolset and call `register_tool()` with your Python function. The function becomes available to the LLM agent during execution, exactly as built-in file or shell tools are exposed.

### Is it possible to run kimi-cli as a background service?

**Yes, via the MCP server or ACP mode.** Implement the MCP protocol defined in [[`src/kimi_cli/mcp.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/mcp.py)](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/mcp.py) to expose the agent over a network socket, or use `run_acp()` to start the Agent Communication Protocol server for inter-process communication.

### Which LLM models are supported when integrating programmatically?

**Any model supported by the underlying `kosong` abstraction layer.** Pass the model identifier to the `model_name` parameter in `KimiCLI.create()`. The system supports various providers through the [`packages/kosong`](https://github.com/MoonshotAI/kimi-cli/tree/main/packages/kosong) interface, allowing you to switch models without changing integration code.