Kimix Quick Start

This guide covers environment setup, installation, and basic CLI usage.

---

Install

From the project root (the directory containing pyproject.toml), run:

python install.py

install.py handles the full setup: dependency sync, native runtime download, and command-line tool registration. Once finished, the kimix command is ready to use.

---

Environment Variables

Configure API keys before running. Priority: JSON config api_key field > KIMI_API_KEY > KIMIX_API_KEY.

Variable	Description
KIMI_API_KEY	Kimi API key
KIMIX_API_KEY	Fallback API key

Linux / macOS:

export KIMI_API_KEY=your-api-key

Windows PowerShell:

$env:KIMI_API_KEY="your-api-key"

---

CLI Usage

Subcommands

Subcommand	Description	Common Options
serve	Start HTTP server (OpenCode style)	--host (default 127.0.0.1), --port (default 4096)
ssecli	SSE CLI debugger for kimix serve. Supports /new, /abort, /status, /sessions, /messages, /clear, /compact[:N], /export[:path], /help; press Ctrl+C or send EOF (Ctrl+D / Ctrl+Z) to exit	--host, --port, --debug (saves raw event log as sse_log_<YYYYMMDD_HHMMSS>.txt)

Examples:

# Start HTTP server
kimix serve --port 4096

# Use SSE CLI debugger
kimix ssecli --host 127.0.0.1 --port 4096 --debug

LLM Config Initialization

If no --config is provided, the built-in default (src/kimix/default_config.json) is used.

Run /init in the interactive terminal to create the default config interactively:

/init

Config fields:

Field	Required	Description
type	Yes	Provider type — see Supported Providers below
model	Yes	Model name for API requests
url	Yes	API base URL
max_context_size	Yes	Max context length (128k, 200k, 256k, 512k, 1M)
capabilities	No	Model capabilities: thinking, always_thinking, image_in, video_in
api_key	No	API key (falls back to env vars)
custom_headers	No	Custom HTTP headers
oauth	No	OAuth config, e.g. {"storage": "file", "key": "my-key"}
loop_control	No	Loop params: max_steps_per_turn, max_retries_per_step, max_ralph_iterations, reserved_context_size, compaction_trigger_ratio
max_tokens	No	Max tokens per request
show_thinking_stream	No	Stream thinking process
thinking_effort	No	off, low, medium, high, xhigh, max
temperature	No	Sampling temperature [0.0, 2.0]
background	No	Background task settings
notifications	No	Notification settings
mcp	No	MCP (Model Context Protocol) config
env	No	Extra env vars (dict)

Supported Providers

type accepts the provider identifiers grouped below (mirroring kimi_cli/llm.py):

Core providers

type	Notes
kimi	Moonshot / Kimi
xai	xAI (Grok)
openai_legacy	OpenAI Chat Completions
openai_responses	OpenAI Responses API
anthropic	Anthropic Claude
google_genai	Google GenAI (legacy alias for gemini)
gemini	Google Gemini (Google AI Studio)
vertexai	Google Vertex AI (legacy alias for vertex)
vertex	Google Vertex AI

OpenAI-compatible providers (Hermes-ported)

ai-gateway, alibaba, alibaba-coding-plan, arcee, azure-foundry, copilot, custom, deepinfra, deepseek, fireworks, gmi, huggingface, kilocode, kimi-coding, nous, novita, nvidia, ollama-cloud, opencode-zen, openrouter, qwen-oauth, stepfun, upstage, xiaomi, zai

Special-mode providers

type	Notes
actual	Actual Computer (Codex-style API)
bedrock	AWS Bedrock (Converse API)
minimax	MiniMax (Anthropic-compatible)
openai-codex	OpenAI Codex (ChatGPT backend)
copilot-acp	GitHub Copilot ACP subprocess (external agent; no in-process LLM)

When api_key / url are omitted, the provider registry falls back to each provider's standard environment variables (e.g. DEEPSEEK_API_KEY, OPENROUTER_API_KEY, XIAOMI_API_KEY, GLM_API_KEY/ZAI_API_KEY, MINIMAX_API_KEY). See kimi-cli/packages/kosong/src/kosong/providers/__init__.py for the full per-provider list.

Load custom config:

kimix --config=<path>

Launch Options

Flag	Description
-c, --clean	Auto-delete cache on exit
--no_think	Disable thinking mode
--no_yolo	Disable YOLO mode
--no_color	Disable colored output
--manually-cot	Enable manual CoT (may use multiple sessions)
--ralph	Enable Ralph mode (optional iteration count)
-s, --skill-dir	Custom skill directory (repeatable)
--config	JSON config path. Searches: cwd parents, package parents, PATH

Auto-loading skill directories: On startup, Kimix also reads .kimix/skill.json in the current directory. If it contains a skill_dir field (string or array of strings) and the directories exist, they are automatically appended to the default skill search paths.

Interactive Commands

Command	Description
<path>	Load file. .py files are executed directly (__file__ points to the file); other files are read entirely as a single prompt
/file:<path>	Read entire file as a single prompt
/todo:<path>	Scan code files for TODO comments and prompt the agent to implement them. Supports .py, C/C++ family (.c/.cpp/.h/.java/.js/.ts/.go/.rs, etc.), Shell (.sh/.bash/.zsh), HTML/XML, Pascal, Lisp, SQL, and more
/clear	Clear current context
/summarize	Summarize context to memory
/exit	Exit
/help	Show help
/context	Print context usage
/fix:<command>	Run command, auto-retry on error
/txt	Multi-line text mode (end with /end, cancel with /cancel)
/init	Interactive LLM config initialization (resets session)
/compact	Compact the current session's conversation context
/export:<path>	Export the current session's messages to the specified file
/resume:<id>	Close current session and resume a session by ID
/store:<id>	Copy the current session to a new named session
/load:<id>	Copy a named session into a new anonymous session
/ralph:on/off/<num>	Set Ralph mode
/reflection	Reflect on the current conversation context, find misunderstandings caused by the current agent design, and change the source code to improve the project (requires a non-empty context; writes a change report to docs/reflection_report_*.md)
/supervisor	Enter multi-line input mode to create a session with the Supervisor role and execute one task (end with /end, cancel with /cancel)
/plan / /plan:<file>	Use the TodoMaker Agent to generate a task plan. Task requirements are provided via multi-line input (end with /end); <file> specifies the plan output file path, and will be overwritten if it already exists. After generation, you can review and modify the plan, then confirm to execute; a review prompt is appended after execution
/cmd:<command>	Execute system command
/code:<path> [args...]	Run a script file (.py or other executables) with optional arguments

---

MCP (Model Context Protocol)

Kimix can act as both an MCP client and an MCP server.

Using MCP Servers

Add an MCP server to Kimix so that its tools, resources, and prompts are available to the agent:

# stdio server
kimix mcp add --transport stdio my-server -- npx -y @example/mcp-server

# streamable HTTP server
kimix mcp add --transport http my-server https://api.example.com/mcp

# list configured servers
kimix mcp list

# test a connection
kimix mcp test my-server

Project-level servers can also be committed to version control in .kimix/mcp.json. Kimix automatically merges global (~/.kimi/mcp.json), project (.kimix/mcp.json), and explicitly supplied configs, with explicit configs taking highest priority.

Serving Kimix as an MCP Server

Expose the current Kimix runtime to external MCP clients such as Claude Desktop or Cursor:

# stdio (for clients that spawn a subprocess)
kimix mcp serve --transport stdio

# streamable HTTP
kimix mcp serve --transport http --host 127.0.0.1 --port 4097

By default the server exposes:

• tools: every tool in the active agent toolset
• resources: AGENTS.md, README.md, and project files under the work directory
• prompts: the agent's system prompt

Use --no-resource or --no-prompt to disable resources or prompts. Use --agent-file to load a specific agent specification.