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

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

Step-by-Step Integration Example

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

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, 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). 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/ 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. 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). 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) 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).
• Leverage the kimi-sdk package in 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).

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) 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 interface, allowing you to switch models without changing integration code.

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