CodeDocs Vault

Kimi Code CLI - Architecture Overview

What is Kimi Code CLI?

Kimi Code CLI is an AI-powered terminal agent built by Moonshot AI. It serves as their equivalent to "Claude Code" - autonomously completing software development tasks via natural language commands.

Tech Stack

Technology Version Purpose
Python 3.12+ (dev targets 3.14) Core language
Typer 0.21.1 Async CLI framework
kosong 0.41.1 Internal LLM orchestration library
fastmcp 2.12.5 MCP (Model Context Protocol) integration
rich 14.2.0 Terminal UI rendering
prompt-toolkit 3.0.52 Interactive terminal input
pydantic 2.12.5 Data validation and settings
uv - Package manager

Directory Structure

kimi-cli/
├── src/kimi_cli/
│   ├── app.py              # KimiCLI - Main orchestrator
│   ├── config.py           # Configuration management
│   ├── llm.py              # LLM provider creation
│   ├── session.py          # Session management
│   ├── agentspec.py        # Agent YAML spec parsing
│   │
│   ├── soul/               # Core agent logic
│   │   ├── kimisoul.py     # Main agent loop
│   │   ├── agent.py        # Runtime, Agent, LaborMarket
│   │   ├── context.py      # Message history
│   │   ├── toolset.py      # Tool registry & execution
│   │   ├── approval.py     # Action gating system
│   │   ├── denwarenji.py   # D-Mail (time-travel)
│   │   └── message.py      # Message utilities
│   │
│   ├── tools/              # Built-in tools
│   │   ├── shell/          # Shell execution
│   │   ├── file/           # File operations
│   │   ├── web/            # Web search/fetch
│   │   ├── multiagent/     # Task, CreateSubagent
│   │   ├── think/          # Thinking tool
│   │   ├── todo/           # Todo management
│   │   └── dmail/          # D-Mail sending
│   │
│   ├── wire/               # Agent-UI communication protocol
│   │   ├── types.py        # Wire message types
│   │   ├── server.py       # Wire server
│   │   └── __init__.py     # Wire utilities
│   │
│   ├── cli/                # CLI entry points
│   ├── agents/             # Agent specifications
│   │   ├── default/        # Default agent config
│   │   └── okabe/          # Alternative agent
│   └── auth/               # OAuth management
│
├── pyproject.toml          # Project metadata & dependencies
└── docs/architecture/      # This documentation

High-Level Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         KimiCLI                                 │
│                      (app.py:54)                                │
│  Entry point that wires together all components                 │
└───────────────────────────┬─────────────────────────────────────┘
                            │
         ┌──────────────────┼──────────────────┐
         │                  │                  │
         ▼                  ▼                  ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│     Runtime     │ │     Agent       │ │    Context      │
│ (agent.py:64)   │ │ (agent.py:157)  │ │ (context.py)    │
│                 │ │                 │ │                 │
│ • config        │ │ • name          │ │ • messages      │
│ • llm           │ │ • system_prompt │ │ • checkpoints   │
│ • session       │ │ • toolset       │ │ • file backend  │
│ • approval      │ │ • runtime       │ │                 │
│ • denwa_renji   │ └────────┬────────┘ └────────┬────────┘
│ • labor_market  │          │                   │
│ • skills        │          │                   │
└────────┬────────┘          │                   │
         │                   │                   │
         └───────────────────┼───────────────────┘
                             │
                             ▼
              ┌──────────────────────────┐
              │        KimiSoul          │
              │    (kimisoul.py:92)      │
              │                          │
              │  Main agent loop that    │
              │  orchestrates turns      │
              │  and steps               │
              └──────────────┬───────────┘
                             │
              ┌──────────────┼──────────────┐
              │              │              │
              ▼              ▼              ▼
       ┌───────────┐  ┌───────────┐  ┌───────────┐
       │  kosong   │  │  Toolset  │  │   Wire    │
       │   LLM     │  │  (tools)  │  │ Protocol  │
       └───────────┘  └───────────┘  └───────────┘

Core Components Summary

Component Location Responsibility
KimiCLI app.py:54 Top-level orchestrator, creates and wires components
KimiSoul soul/kimisoul.py:89 Main agent loop, manages turns and steps
Runtime soul/agent.py:64 Immutable execution context with all dependencies
Agent soul/agent.py:157 System prompt + toolset configuration
Context soul/context.py Conversation history with checkpoint support
KimiToolset soul/toolset.py:71 Tool registry, loading, and execution
Approval soul/approval.py Action gating (approve/reject tool calls)
DenwaRenji soul/denwarenji.py D-Mail time-travel messaging

LLM Providers

Kimi CLI supports multiple LLM backends through the kosong library:

Provider Type Notes
Kimi kimi Moonshot AI (primary/default)
OpenAI openai_legacy, openai_responses Standard and responses API
Anthropic anthropic Claude models
Google google_genai, gemini, vertexai Gemini and Vertex AI

Built-in Tools

Category Tools Description
File ReadFile, WriteFile, StrReplaceFile, Glob, Grep File system operations
Shell Shell Bash/PowerShell command execution
Web SearchWeb, FetchURL Web search and page fetching
Multi-agent Task, CreateSubagent Subagent creation and task delegation
Planning Think, SetTodoList Internal reasoning and task tracking
Time-travel SendDMail Send messages to past checkpoints

Key Design Patterns

  1. Dependency Injection - Tools receive dependencies at instantiation
  2. Protocol/Structural Subtyping - Soul interface enables alternative implementations
  3. Context Variables - Track current tool call across async boundaries
  4. Wire Protocol - Decouple soul logic from UI rendering
  5. Checkpoint-based Time-travel - D-Mail enables reverting to past states

Data Flow Overview

User Input
    │
    ▼
┌─────────────────┐
│   KimiSoul.run  │ ← Checks for slash commands (skills/flows)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  _agent_loop    │ ← Iterates until no tool calls remain
└────────┬────────┘
         │
    ┌────┴────┐
    │  _step  │ ← Single LLM call + tool execution
    └────┬────┘
         │
         ├──► kosong.step() → LLM response
         │
         ├──► toolset.handle() → Execute tools in parallel
         │
         └──► context.append() → Save to history