Where to Find Example Usage of kimi-cli: A Complete Guide to the Examples Directory

kimi-cli ships self-contained example projects in the repository's top-level examples/ folder that demonstrate how to run the agent, invoke built-in tools, and extend functionality with custom plugins.

The MoonshotAI/kimi-cli repository provides a comprehensive collection of runnable demonstrations for developers seeking example usage of kimi-cli. These projects live in the examples/ directory and illustrate everything from simple plugin creation to low-level wire protocol integration, all executable with uv run without additional setup.

Exploring the examples/ Directory Structure

The examples/ folder contains six distinct projects, each focused on specific capabilities of the agent framework. Every subdirectory includes a dedicated README with usage instructions and a runnable entry point.

Plugin and Tool Development Examples

• sample-plugin: Demonstrates creating a simple plugin and calling a custom tool from the CLI. Run with:

  uv run examples/sample-plugin/main.py

  Source: [examples/sample-plugin/README.md](https://github.com/MoonshotAI/kimi-cli/blob/main/examples/sample-plugin/README.md)

• custom-tools: Shows how to add user-defined tools (such as a custom ls command) and load them via a custom agent specification. Run with:

  uv run examples/custom-tools/main.py

Integration and Protocol Examples

• kimi-psql: An AI-assisted PostgreSQL REPL that combines the standard psql client with the ExecuteSql tool. Run with:

  uv run examples/kimi-psql/main.py -h localhost -p 5432 -U postgres -d mydb

  Source: [examples/kimi-psql/README.md](https://github.com/MoonshotAI/kimi-cli/blob/main/examples/kimi-psql/README.md)

• kimi-cli-wire-messages: Illustrates how to drive the agent programmatically by sending JSON-RPC wire messages, useful for testing or embedding. Run with:

  uv run examples/kimi-cli-wire-messages/main.py

Custom Agent Configurations

• custom-kimi-soul: Demonstrates building a bespoke KimiSoul instance with a custom toolset. Run with:

  uv run examples/custom-kimi-soul/main.py

• custom-echo-soul: A minimal "echo" soul that returns user input directly, useful for learning the agent loop. Run with:

  uv run examples/custom-echo-soul/main.py

Core CLI Usage Patterns

Beyond the example projects, the main entry point in src/kimi_cli/cli/__init__.py provides several command-line modes. These commands demonstrate practical example usage of kimi-cli for common workflows:

# Show the help banner

uv run kimi --help

# Start an interactive session (default AI-assisted terminal)

uv run kimi

# Run one-off commands without entering the REPL

uv run kimi /setup          # LLM configuration wizard

uv run kimi /login          # Authenticate with Kimi Code service

uv run kimi acp             # Launch ACP server mode

uv run kimi mcp list        # List configured MCP servers

uv run kimi web             # Start the built-in web UI

Programmatic Implementation Examples

For developers integrating kimi-cli into Python applications, the source code reveals several implementation patterns found in the examples/ directory.

Launching the Interactive REPL

To programmatically launch the interactive shell equivalent to uv run kimi, instantiate the main CLI coroutine:

import asyncio
from kimi_cli.cli import main as kimi_main

if __name__ == "__main__":
    asyncio.run(kimi_main())   # launches the interactive AI shell

Creating Custom Tools

In examples/sample-plugin/scripts/greet.py, the Greet tool extends CallableTool2 to add custom functionality:

from kimi_cli.tools.tool import CallableTool2, ToolOk

class Greet(CallableTool2):
    name = "Greet"
    description = "Return a friendly greeting."
    async def __call__(self, _: None) -> ToolOk:
        return ToolOk(output="👋 Hello from the sample plugin!")

This pattern leverages kimi_cli.soul.agent.load_agent and kimi_cli.soul.runtime.Runtime to register the tool within a custom agent specification.

Handling Wire Protocol Messages

For low-level integration, the examples/kimi-cli-wire-messages project demonstrates driving the agent via JSON-RPC. The implementation uses JsonRpcRequest from src/kimi_cli/wire/jsonrpc.py:

from kimi_cli.wire.jsonrpc import JsonRpcRequest
from kimi_cli.soul.kimisoul import KimiSoul

async def demo():
    soul = await create_some_soul()
    request = JsonRpcRequest(method="run", id=1, params={"user_input": "Explain the repo structure"})
    await soul.handle_wire(request)   # processes the request and emits UI events

This approach builds a KimiSoul instance and feeds it wire messages directly, bypassing the terminal UI.

Key Source Files for Reference

Understanding these core files provides context for the example implementations:

• src/kimi_cli/cli/__init__.py: Typer-based command-line entry point defining the kimi command.
• src/kimi_cli/app.py: Contains KimiCLI.create which builds configuration, LLM, and runtime objects.
• src/kimi_cli/soul/kimisoul.py: Implements the main agent loop that receives input, runs tools, and emits wire events.
• src/kimi_cli/soul/agent.py: Defines Runtime and Agent classes that glue together configuration, tools, and the soul.
• src/kimi_cli/tools/agent/: Directory containing built-in tools (Shell, File, Web) available to the agent.
• src/kimi_cli/wire/: JSON-RPC wire protocol implementation for UI-to-soul communication.

Summary

• The examples/ directory contains six self-contained, runnable projects demonstrating example usage of kimi-cli ranging from simple plugins to complex protocol integrations.
• All examples execute with uv run without additional dependencies, utilizing minimal pyproject.toml configurations.
• Wire-level usage is demonstrated in examples/kimi-cli-wire-messages, showing how to drive KimiSoul programmatically via JSON-RPC.
• Custom tool development follows the CallableTool2 pattern shown in examples/sample-plugin, integrated through Runtime and Agent classes.
• Core CLI functionality spans interactive REPLs, one-off commands, ACP server mode, and web UI launch capabilities.

Frequently Asked Questions

Where are the kimi-cli examples located in the repository?

All official examples reside in the top-level examples/ folder of the MoonshotAI/kimi-cli repository. Each subdirectory contains a complete, runnable project with its own README and entry point.

How do I run the kimi-cli examples without installing dependencies?

Each example includes a pyproject.toml configured for uv. Simply execute uv run examples/<example-name>/main.py from the repository root, and uv will automatically handle dependencies.

Which example shows how to create custom tools for kimi-cli?

The sample-plugin and custom-tools examples demonstrate extending the agent with user-defined functionality. They show how to subclass CallableTool2, implement the __call__ method, and register tools via the Runtime class in src/kimi_cli/soul/agent.py.

How can I programmatically control kimi-cli without the terminal UI?

Use the kimi-cli-wire-messages example, which illustrates driving the agent via JSON-RPC wire messages. This approach creates a KimiSoul instance and sends JsonRpcRequest objects directly to handle_wire(), enabling headless operation or custom UI integration.

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