Kimi Code Reference Moonshot AI's terminal coding agent

A single-binary terminal agent from the lab behind the Kimi K-series: three permission modes, a plan mode that writes only the plan, goals that persist across turns, swarms of item-based subagents, and a local web UI and ACP server on the same engine. It reads the same AGENTS.md and ~/.agents/ layout as every other agent, and imports Claude Code and Codex configuration in one command. Guide cards explain the mechanisms; the index below is a searchable dictionary of every command, flag, slash command, config key, hook event and tool.

CLIslash commandconfig / TOMLtool / hookmodelanti-pattern August 2026

▾How Kimi Code works

the modes, the extension layer, and what it costs to run · click to collapse

What Kimi Code is

Moonshot · CLI

A terminal coding agent from Moonshot AI: reads and edits files, runs shell commands, searches with a bundled ripgrep, fetches the web, plans, and applies changes after you approve. Written in TypeScript, shipped as a single binary (no Node needed), open source at MoonshotAI/kimi-code. The command is kimi.

MechanismWhat it gives you
Three permission modesmanual · yolo (still asks about .env, SSH keys, plan exit) · auto (never asks)
Plan modeWrite/Edit restricted to the plan file; exit needs your approval even in YOLO
/goalA persistent objective the agent works toward across turns — complete, blocked or paused
/swarm · AgentSwarmOne prompt template × N items → N parallel subagents
Web UI · ACP · RESTThe same engine in a browser, in Zed/JetBrains, or behind an API
Video inputPaste a clip; the model reads it. Unusual among agents

Authenticate with a Kimi Code plan (OAuth, kimi.ai global or kimi.com mainland) or a Kimi Platform API key; or point a provider at Anthropic, OpenAI, Google or any OpenAI-compatible endpoint.

The 30-second orientation: install, /login, /init to generate an AGENTS.md (or /import-from-cc-codex if you already have Claude Code config), then a real task with Shift-Tab plan mode on.

Install & first run

5 minutes
curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash # macOS / Linux irm https://code.kimi.com/kimi-code/install.ps1 | iex # Windows (needs Git for Windows) npm install -g @moonshot-ai/kimi-code # alternative; Node 22.19+

The script puts kimi in ~/.kimi-code/bin/ and adds it to your shell profile — so it is not on the PATH in non-interactive shells until you source the profile or use the absolute path. On Windows it runs in the bundled Git Bash; set KIMI_SHELL_PATH if Git is somewhere unusual.

kimiinteractive TUI in this directory kimi -ccontinue the last session here kimi -p "…"headless; auto permission, deny rules still apply kimi --planstart in plan mode kimi doctorvalidate config.toml and tui.toml kimi upgradecheck and install the latest

Two products install a binary called kimi. This is Kimi Code CLI (package @moonshot-ai/kimi-code, home ~/.kimi-code/). The older Python kimi-cli is the legacy one; kimi migrate pulls its sessions across.

First session

/login → Kimi Code (OAuth device code) or Platform API key. Then /init analyses the codebase and writes AGENTS.md. Read-only tools run without asking; the first write shows an approval panel with approve for this session.

Permission modes

3 + rules
ModeRuns without asking
manual (default)Read-only tools: Read, Grep, Glob, ReadMediaFile, WebSearch, FetchURL, task queries
yolo · -yRegular tool calls. Still asks for sensitive files (.env, SSH keys), plan-mode exit, and questions to you
auto · --autoEverything, including sensitive files and plan exits. The agent never asks. What -p uses

Switch with /permission, /yolo, /auto; set a default with default_permission_mode. --yolo and --auto are mutually exclusive; -p accepts neither.

Rules survive every mode

[[permission.rules]] decision = "deny" # allow · deny · ask pattern = "Bash(rm -rf*)" # Tool or Tool(arg-pattern) scope = "user" # turn-override · session-runtime · project · user

Matched in order; Bash(command-pattern), Read(path-pattern), mcp__github__* with */**. Static deny rules apply in -p and YOLO alike. "Always allow" choices made in the approval panel propagate to subagents.

Trust prompt. A new folder is untrusted until you say otherwise; project-level MCP servers and hooks are shown in the prompt, which defaults to Don't trust. A cloned repo's .kimi-code/ can replace the main agent — read it first.

Plan mode & goals

what must become true

Plan mode

Shift-Tab or /plan. The agent explores with read-only tools and writes a plan; Write/Edit are restricted to the plan file and TaskStop is blocked; Bash follows the normal rules. ExitPlanMode presents the plan — with up to three alternative approaches — and needs your approval even in YOLO; only auto self-approves. /plan clear discards it; default_plan_mode = true starts every session in it.

Goals

/goal Fix every failing checkout test, add tests for each fix, and run the checkout suite green. Stop if still blocked after 20 turns.

A goal says what must become true, not what to do next. After every turn Kimi checks: complete (clears and summarises), blocked (needs input, impossible, or budget hit — writes why), or paused (you, an interrupt, a resume, or an error). Name the finish line and the evidence; write stop conditions into the text — there is no separate limit flag. 4 000-character cap.

/goal · /goal statusobjective, state, elapsed, turns, tokens /goal pause · resume · cancellifecycle /goal replace <obj>swap the objective /goal next <obj>queue one; invisible to the agent until the current completes /goal next managereorder, edit, delete the queue kimi -p "/goal …"headless; exit 0 done · 3 blocked · 6 paused

Good goals: a failing suite to make green, a build to fix at the root cause, an ordered list of artifacts that must exist. Bad goals: "find all bugs", "greetings", "make a game in one file". A fork does not carry the goal.

Subagents & swarm

isolated contexts
Built-inCan
coder (default)Read, write, run, search — most of the main agent's tools; cannot spawn further subagents
exploreRead-only. Survey a repo without touching it
planPlanning only — no shell at all

The main agent dispatches on its own (each dispatch is an approval unless allowed), or you say "use explore to map the auth code". Each subagent has its own context; only its final message returns. /tasks shows background ones live; /btw forks a side conversation that never touches the main turn.

Swarm

/swarm write a unit test file for every module under src/billing/

AgentSwarm takes a prompt_template with {{item}} and an items list; one subagent per item, in parallel, with rate-limit-aware retries and a live progress card. /swarm on|off toggles the mode; /swarm <task> runs one and turns it off after. From manual it offers to switch to auto or yolo first. Cap the ramp with KIMI_CODE_AGENT_SWARM_MAX_CONCURRENCY.

Custom agents

A Markdown file with frontmatter — name, description, tools, disallowedTools, subagents — and a body that is the system prompt. A reviewer with tools: [Read, Grep, Glob] cannot edit: the list is enforced before execution, not just shown to the model. Run one as the main agent with --agent reviewer. Subagent timeout 2 h ([subagent] timeout_ms).

Skills, agents & plugins

extension layer

Where things live — four tiers

ScopeSkillsAgents
Project.kimi-code/skills/ · .agents/skills/.kimi-code/agents/ · .agents/agents/
User~/.kimi-code/skills/ · ~/.agents/skills/~/.kimi-code/agents/ · ~/.agents/agents/
Extraextra_skill_dirsextra_agent_dirs
Built-in / pluginlowestplugin beats built-in

Project beats user beats extra beats built-in. The generic ~/.agents/ directories are shared with other tools and stay under the real home even when KIMI_CODE_HOME moves everything else.

Skills — a folder, or one file

--- name: release-notes description: Draft release notes from merged PRs since the last tag whenToUse: when asked for release notes or a changelog entry type: prompt # prompt · inline · flow (manual only) disableModelInvocation: true arguments: [since] --- Run `gh pr list --state merged --search "merged:>$since" …`

name and description are required in a SKILL.md. Invoke as /skill:release-notes v1.2, or just /release-notes if no system command owns the name; sub-skills appear as /parent.child. Type / after whitespace to stack several skills in one prompt. Nesting 3 deep. $ARGUMENTS, $0, $name, ${KIMI_SKILL_DIR} expand in the body.

Plugins

/plugins — Installed · Official · Curated · Custom tabs; install from a GitHub URL, zip or path. Bundle skills, agents, MCP servers and instructions. Per-user only; /reload after changes. Official: Kimi Datasource (market, macro, academic and Chinese government data), WebBridge (drive your browser), Computer Use (macOS/Windows desktop).

Hooks

fail-open
[[hooks]] event = "PreToolUse" # see the event table matcher = "Bash" # regex on the event's target command = "node ~/.kimi-code/hooks/guard.mjs" timeout = 5 # seconds, 1–600, default 30

Event JSON arrives on stdin (hook_event_name, session_id, cwd, plus tool_input etc.). Exit 2 blocks and stderr becomes the reason the model sees; exit 0 allows and stdout may be appended to context; any other exit, a crash or a timeout allows. Or return {"hookSpecificOutput":{"permissionDecision":"deny",…}}.

BlockableObservation only
PreToolUse · Stop · UserPromptSubmitPostToolUse · PostToolUseFailure · PermissionRequest/Result · SessionStart/End · SessionHeartbeat · SubagentStart/Stop · TaskStarted · TurnStarted · StopFailure · Interrupt · PreCompact/PostCompact · Notification · UserPromptQueued

Fail-open is the point to remember. A hook that errors lets the call through, so hooks are for alerts and lightweight interception — the docs say so. The hard guarantee is a deny permission rule or an agent tools list. Stop is the one to hang a test run on: block it and the model keeps working.

Context, sessions & memory

reserved_context_size
/new · /clearfresh session /compact [hint]compress; the hint steers what is kept /undo [n]drop recent prompts (and their todo/plan state); files untouched /forkindependent copy; you stay put; kimi --resume … goes to the clipboard /btw [q]side question in a forked sub-agent; never enters history /usage · /statustokens, context, quota · version, model, cwd, mode /sessions · /titlebrowse and resume · rename (200 chars)

Auto-compaction fires when the remaining window drops below [loop_control] reserved_context_size. Sessions live under ~/.kimi-code/sessions/<workDirKey>/<id>/ as wire.jsonl event streams — do not edit them; kimi export zips one for a bug report, /export-md writes it as Markdown, kimi vis replays it in a browser.

Instructions: the project's AGENTS.md; global Kimi-specific ~/.kimi-code/AGENTS.md; cross-tool ~/.agents/AGENTS.md. ~/.kimi-code/SYSTEM.md replaces the system prompt outright (${base_prompt}, ${agents_md}, ${skills} placeholders).

The cache-expiry hint: resume after a long idle and the TUI warns the prompt cache has likely expired and offers to compact or start fresh. That dialog is a bill-saver — cached input on K2.7 is a fifth of the fresh price.

Web UI, ACP & headless

one engine
kimi weblocal server + browser UI; loopback only; bearer token in the banner /webopen the current session in it kimi acpAgent Client Protocol over stdio — Zed, JetBrains kimi -p "…" --output-format stream-jsonone JSON object per line; thinking to stderr kimi -p --agent reviewer "…"headless with a custom main agent kimi -m <alias> -p "…"a different model for this run

The web UI adds what a TUI cannot: sidebar tabs, a session manager, a goal strip with a token-budget bar, swarm cards, Cmd+K search, and GET /openapi.json for the REST API. --host binds all interfaces — only behind your own TLS proxy; --dangerous-bypass-auth means what it says. kimi web rotate-token revokes the old token everywhere.

Print mode stays alive for background tasks: with [background] print_background_mode = "steer" (default) each completion re-enters the agent as a synthetic message until nothing is pending. Set "exit" for a pure one-shot.

Zed: agent_servers → {"command":"kimi","args":["acp"]}; GUI-launched IDEs do not inherit the shell PATH, so use the absolute path to ~/.kimi-code/bin/kimi.

Models & cost

Aug 2026
ModelCtxIn $/M (hit)Out $/M
Kimi K31M3.00 (0.30)15.00
Kimi K2.7 Code256k0.95 (0.19)4.00
Kimi K2.6256k0.954.00
Kimi K2.5256k0.603.00

Platform API prices. A Kimi Code plan (from about $19/month) provisions kimi-code/k3, kimi-for-coding and -highspeed under the managed:kimi-code provider against a quota instead; /usage shows what is left. K3 declares support_efforts = [low, high, max]; the rest think at one level.

Spend it where it matters

The subagent model pool ([secondary_model], experimental: KIMI_CODE_EXPERIMENTAL_SECONDARY_MODEL=1) lets the main agent pick a cheap model for explore and swarm workers and K3 for the hard subtask; force = true pins them all. Register a second alias for the same model with [models."k3-max".overrides] default_effort = "max" to put effort in the pool too.

Any provider: type = "anthropic" | "openai" | "openai_responses" | "google-genai" | "vertexai", or kimi provider catalog add anthropic --api-key … from the models.dev catalog. Credentials come only from config.toml — exporting KIMI_API_KEY in the shell does nothing unless it is in the provider's [env] table or KIMI_MODEL_*.

Config it already understands

adoption
It readsWhere
AGENTS.mdRepo root — the cross-vendor standard; /init writes one
~/.agents/ skills, agents, AGENTS.mdThe shared user-level layout other agents also scan
.agents/ in a projectSame, project-scoped
Claude Code agent filesComma-separated tools: loads; model: is ignored
/import-from-cc-codexImports Claude Code and Codex instructions, skills and MCP settings in one go
mcp.jsonThe common {"mcpServers":{…}} shape, user and project level

The durable point is the same as on the other sheets: the instruction layer is portable. Time spent on AGENTS.md and ~/.agents/skills/ is not a bet on Moonshot.

Idioms

what pays off

The everyday invocation

kimi -y --plan # approve regular calls; still asks about secrets and the plan

Order of operations

  • Deny rules before YOLO. Bash(rm -rf*), Bash(git push --force*), Read(**/.env) — they apply in every mode, including -p.
  • Tool lists over instructions. A reviewer agent with no Edit cannot edit; a polite request can be drifted from.
  • Goals for finish lines, prompts for steps. If you can name the evidence, it is a goal.
  • Swarm when the items are independent — one file, one module, one issue each — and the template carries the verification step.
  • Ctrl-S to steer, not Esc to interrupt. Injecting a correction mid-turn keeps the work; interrupting throws it away.

Give it something worth reading

The machinery operates on context. /init once, then an AGENTS.md you prune, a wiki it can @-reference, and CLIs for your data. None of that is Kimi-specific, and all of it matters more than any setting above.

A Chinese model at the keyboard

the question under the tooling

Kimi is built by Moonshot AI in Beijing. Using it for real work raises questions the other sheets on this site do not, and it is worth being able to answer them accurately — both the objections and why they may not apply to you.

Where the data goes

With a Kimi Code plan or Platform key, your prompts, file contents and tool output are processed on Moonshot's servers, under PRC jurisdiction. Two regions exist — kimi.com (mainland) and kimi.ai (global, api.moonshot.ai) — and the CLI records which you logged into. Code that cannot leave your organisation should not go through either. The same is true of any hosted API; the difference is whose law applies to the logs.

Telemetry is on by default (telemetry = false turns it off); sessions, including tool output and credentials traces, are stored locally under ~/.kimi-code/sessions/.

What is actually open

The CLI is open source (MIT) and the K-series weights are published under a modified MIT licence — which is how K2.x appears in Copilot's model picker, on OpenRouter, and on Western-hosted inference providers. That is the answer to the data question: the model is separable from the company. Run it through a US or EU host, or on your own hardware, and nothing goes to Beijing. The CLI's provider table takes any OpenAI-compatible endpoint.

Benchmarks put K3 at or near the top of the open-weight tier for agentic coding, and K2.7 Code is a fraction of frontier prices. That is the reason to bother.

What it will not say

Like every model trained and served under Chinese regulation, Kimi declines or deflects on politically sensitive topics about China. For software work this almost never surfaces. For research, policy or journalism it is a real limitation, and the honest position is to know it rather than discover it.

Policy. Many employers ban Chinese-hosted AI services outright while permitting self-hosted open weights; some ban both. Check before the first session at work — it is the one question on this sheet you cannot answer from the docs.

The short version: the hosted service is a jurisdiction choice, the weights are not, and the tooling is good enough that the choice is worth making deliberately rather than by default.

▾Index

every command, flag, slash command, config key, hook event and tool · use the search box above · click to collapse

CLI

kimi

Launching

kimiStart the interactive TUI in the current directory. Prompts to trust the folder first.
-c, --continueContinue the most recent session in this working directory.
-S, --session [id]Resume by ID, or pick interactively without one. -r/--resume is a hidden alias. Mutually exclusive with -c.
-p, --prompt "<prompt>"Run one prompt and print the response. Auto permission; static deny rules still apply. Cannot combine with -y, --auto or --plan.
--output-format text|stream-jsonPrint-mode output. stream-json emits one JSON object per line on stdout; thinking and progress go to stderr.
-m, --model <alias>Model alias for this launch. Defaults to default_model in config.toml.
-y, --yoloAuto-approve regular tool calls; still asks about sensitive files, plan exit and questions. --yes and --auto-approve are hidden aliases.
--autoAuto permission mode: every approval handled automatically, the agent never asks. Exclusive with --yolo.
--planStart the session in Plan mode. Also overrides a resumed session's saved mode.
--agent <name>Start with a named agent as the main agent — built-in or discovered file. Not with --session/--continue.
--agent-file <path>Load one agent file at highest priority and select it. Cannot repeat or combine with --agent.
--add-dir <dir>Add another workspace directory for this session. Repeatable.
--skills-dir <dir>Load skills from this directory instead of the auto-discovered ones. Repeatable. extra_skill_dirs adds rather than replaces.
-V · -hVersion · help.

Subcommands

kimi login [--region]OAuth device-code login without the TUI. --region mainland-cn (kimi.com) or global (kimi.ai). Exit 0 ok, 1 cancelled.
kimi doctor [config|tui] [path]Validate config.toml and tui.toml without starting. Exit 1 if any requested file is missing or invalid.
kimi export [id] -o -yZip a session (most recent by default) for sharing or a bug report. --no-include-global-log to drop the shared log.
kimi web [--port] [--host] [--no-open]Run the local REST/WebSocket server and open the web UI. Loopback only by default; bearer token printed at start.
kimi web rotate-tokenNew persistent server token in ~/.kimi-code/server.token; the old one stops immediately.
kimi acp [--login] [--region]ACP server over stdio for IDEs. --login runs the device flow and exits.
kimi vis [id] [--port] [--no-open]Open the session visualizer in a browser; home view lists sessions.
kimi provider add|remove|list|catalogManage providers non-interactively. list --json for scripting.
kimi provider catalog add <id> --api-keyImport a provider from the models.dev catalog; --default-model sets the default. Works offline from a built-in snapshot.
kimi upgrade · updateCheck and install the latest version. Native installs swap the binary in on next start.
kimi migratePull sessions and config across from the legacy Python kimi-cli.
kimi server …Deprecated — prints a notice and exits 1. Only kimi server kill still works, for pre-0.28 background servers.

Slash commands

in the TUI

Session

/new · /clearStart a fresh session, discarding the current context.
/sessions · /resumeBrowse historical sessions and switch to one.
/forkIndependent copy with full history; you stay in the current one. A goal is not copied. Prints a kimi --resume command.
/title [text] · /renameShow or set the session title (max 200 chars).
/compact [instruction]Compress context; the instruction hints what to keep.
/undo [n]Drop recent prompts from context (selector without a count). Rolls back todo and plan state; does not revert code. Not past a compaction.
/reload · /reload-tuiRe-read config.toml and tui.toml in place · UI preferences only.
/initAnalyse the codebase and generate AGENTS.md.
/export-md [path] · /export-debug-zipExport as Markdown · as the same debug ZIP kimi export makes.
/copyCopy the last assistant message.
/add-dir [path|list]Add a workspace directory; offers to remember it in .kimi-code/local.toml.
/webOpen this session in the web UI — attach to a running server or start one after the TUI exits.
/tasks · /taskBackground task list with live subagent progress.

Modes & goals

/yolo [on|off] · /yesToggle YOLO. Plan-mode exit still needs approval.
/auto [on|off]Toggle auto permission mode — never asks.
/plan [on|off] · /plan clearToggle Plan mode (Shift-Tab) · discard the current plan.
/permissionPick a permission mode from a menu.
/swarm on|off · /swarm <task>Toggle swarm mode, or run one task as a swarm and turn it off after. Offers auto/yolo from manual.
/goal <objective>Start goal mode: work across turns until complete, blocked or paused. Put stop conditions in the text.
/goal status · pause · resume · cancel · replaceInspect and control the current goal. Use -- before an objective that starts with one of these words.
/goal next <obj> · /goal next manageQueue a goal (starts now if none is active) · reorder, edit, delete the queue.

Account, config & info

/login · /logoutKimi Code OAuth or Platform API key · clear credentials.
/providerInteractive provider manager.
/modelSwitch the model for this session.
/secondary-model · /subagent-modelPick the default subagent model (writes [secondary_model]). Needs the experiment flag.
/settings · /experiments · /editor · /themeSettings panel · experimental features · external editor for Ctrl-G · colour theme.
/btw [question]Side conversation in a forked sub-agent; the main turn is untouched.
/usage · /statusTokens, context and quota · version, model, cwd, permission mode.
/mcp · /pluginsMCP servers and connection status · plugin manager (list, install, enable, disable, remove, marketplace).
/help · /feedback · /version · /exitCommands and keys · send a bug with logs · version · quit (also Ctrl-C twice, Ctrl-D).

Built-in skills

/mcp-config [login <server>]Add, edit, delete MCP servers interactively; complete OAuth for one.
/update-configInspect or edit config.toml and tui.toml through the agent.
/import-from-cc-codexImport Claude Code and Codex instructions, skills and MCP settings.
/check-kimi-code-docsAnswer Kimi Code usage questions against the official docs.
/custom-theme · /sub-skill.review · .consolidateCreate a TUI theme · reorganise skills into sub-skill bundles (proposal, then apply).
/skill:<name> [args] · /<parent>.<child>Invoke an external skill; /name works when no system command owns it. Type / after whitespace to stack several in one prompt.

Keys

Shift-TabToggle Plan mode.
Ctrl-SSteer: inject the input into the running turn without interrupting.
Esc · Ctrl-CInterrupt streaming or compaction; close a popup. Ctrl-C twice while idle exits.
!Shell mode in an empty box; output enters context. Ctrl+B backgrounds a running command. Long output is collapsed.
@File-path completion; the agent loads the file when it reads the message.
Ctrl-G · Ctrl-V / Alt-VEdit the prompt in $EDITOR · paste an image or video (Windows: Alt-V).
Ctrl-O · Ctrl-T · Ctrl-EToggle tool output · the todo list · full diff in an approval panel.
Ctrl-- · Esc EscUndo · open the undo selector while idle.
1 / 2 / 3Pick an approval option by number; Esc, Ctrl-C or Ctrl-D rejects.

Config & files

TOML

Locations

~/.kimi-code/ · KIMI_CODE_HOMEEverything: config, sessions, credentials (0600), logs, plugins, managed rg and fd. Relocate with the variable.
config.tomlModel, providers, permission, hooks, loop control. Credentials are read only from here.
tui.tomlTheme, render_latex, editor, notifications, [upgrade] auto_install, [status_line] items or command.
mcp.json · .kimi-code/mcp.jsonMCP servers, user and project level; project wins on a name clash.
AGENTS.md · ~/.kimi-code/AGENTS.md · ~/.agents/AGENTS.mdProject · global Kimi-specific · global cross-tool instructions.
~/.kimi-code/SYSTEM.mdReplaces the main agent's system prompt. ${base_prompt}, ${agents_md}, ${skills}, ${cwd}, ${os} placeholders.
.kimi-code/local.tomlPer-project remembered settings such as extra workspace directories.
sessions/<workDirKey>/<id>/state.json plus agents/*/wire.jsonl event streams. Do not edit; may contain credentials traces.

Top-level keys

default_modelAlias from [models]. Set it deliberately.
default_permission_modemanual (default) · yolo · auto for new sessions.
default_plan_modetrue starts every session in Plan mode.
extra_skill_dirs · extra_agent_dirsExtra search directories, layered on the defaults — team-shared skills and agents.
merge_all_available_skills · builtin_product_skillsMerge skills from every tier (default true) · offer the self-documenting built-ins (true; false trims context).
telemetry = falseAnonymous telemetry is on unless explicitly false.

Tables

[providers.<id>]type (kimi · anthropic · openai · openai_responses · google-genai · vertexai), api_key, base_url, custom_headers, [env] fallback table.
[models."<alias>"]provider, model, max_context_size (required); capabilities, support_efforts, default_effort, display_name, max_output_size. Quote aliases with dots.
[models."<alias>".overrides]User overrides that survive provider refreshes — the way to pin default_effort or max_context_size.
[secondary_model]Subagent model pool: default_model, a models table with hints, force = true to pin. Experimental flag required.
[thinking]enabled (true), effort (low…max where supported), keep = "all".
[loop_control]max_steps_per_turn, max_attempts_per_step (10, transient errors only), reserved_context_size — the auto-compaction trigger.
[background]max_running_tasks, keep_alive_on_exit, bash_task_timeout_s (600), bash_auto_background_on_timeout, print_background_mode = steer · drain · exit.
[subagent] timeout_msWall-clock cap per subagent, default 7 200 000 (2 h); 0 = none.
[tools] enabled · disabledGlobal tool allow/deny lists, intersected with every agent's own. Globs only for mcp__ names.
[[permission.rules]]decision allow|deny|ask, pattern Tool or Tool(arg-pattern), scope, reason. Matched in order; deny survives every mode.
[[hooks]]event, matcher (regex), command, timeout (1–600 s). Exactly these four fields.
[mcp] startup_timeout_ms · tool_timeout_msGlobal MCP connection (30 s) and call (60 s) timeouts; per-server values in mcp.json win.
[services.moonshot_search|moonshot_fetch]The built-in WebSearch and FetchURL backends: base_url, api_key.
[identity] name · slugWhat the agent calls itself and the User-Agent / MCP client name it announces.
[image] max_edge_px · read_byte_budgetImage compression before send: 2000 px longest edge, 256 KB per model-read image.

Environment

KIMI_CODE_HOMEMove the whole data root. Generic ~/.agents/ stays under the real home.
KIMI_MODEL_*Synthesise a temporary provider and model from the environment — nothing persisted.
KIMI_CODE_EXPERIMENTAL_FLAG=1Master switch for experiments: _SECONDARY_MODEL, _SUBAGENT_FORK, _AUTO_SESSION_TITLE individually.
KIMI_CODE_AGENT_SWARM_MAX_CONCURRENCYCap concurrent swarm subagents during the initial ramp.
KIMI_LOOP_MAX_STEPS_PER_TURN · KIMI_SUBAGENT_TIMEOUT_MSOverride the config values; environment wins.
KIMI_SHELL_PATHWindows: absolute path to Git Bash's bash.exe when it is not where the installer expects.
KIMI_CODE_TUI_FULL_SCREEN=1Experimental fullscreen TUI.
KIMI_REGISTRY_API_KEYBearer for kimi provider add / catalog add when --api-key is omitted.

Skill & agent frontmatter

name · descriptionBoth required in a directory-form SKILL.md; a flat .md falls back to filename and first line.
whenToUseWhen the model should reach for it. Also when-to-use, when_to_use.
type: prompt · inline · flowflow is manual-only; inline is callable by the Skill tool.
disableModelInvocation: trueOnly you can run it. Right for side effects.
arguments · $ARGUMENTS · $0 · $name · ${KIMI_SKILL_DIR}Declare named parameters; placeholders expand in the body. Quoted positional args are honoured.
tools · disallowedToolsAgent tool allow/deny lists; exact names, mcp__server__* globs. Enforced before execution. tools: [] disables all.
subagentsWhich sub-agent types this agent may delegate to. Default coder, explore, plan — none of which delegate further.
override: trueLet a file replace a same-name built-in. agent.md with override replaces the default main agent — a trust concern in cloned repos.

Tools & hooks

what the agent calls

Built-in tools

Read · Grep · Glob · ReadMediaFileAuto-allowed. Read caps at 1000 lines / 100 KB; Grep is ripgrep; Glob honours .gitignore; media up to 100 MB.
Write · EditNeed approval. Edit requires a unique match or replace_all; since 0.38 both require reading an existing file first.
BashNeeds approval. 60 s foreground default, 5 min max; on timeout it moves to the background rather than dying. run_in_background with a description.
WebSearch · FetchURLAuto-allowed; backed by [services]. FetchURL returns extracted text, not HTML.
EnterPlanMode · ExitPlanModeEnter; exit presents the plan (1–3 alternative approaches) for your approval.
TodoListVisible subtask list; Ctrl-T expands it.
AgentSpawn a subagent: prompt, description, subagent_type (coder), resume, run_in_background, model (with a pool).
AgentSwarmprompt_template with {{item}} × items → parallel subagents; resume_agent_ids to continue. Must run alone in a response.
AskUserQuestion1–4 structured questions with 2–4 options each.
SkillInvoke an inline-type skill by name; rejected if disableModelInvocation.
TaskList · TaskOutput · TaskStop · WaitForBackground task control. WaitFor (0.38) blocks the turn up to 600 s for a task instead of ending it.
CronCreate · CronList · CronDeleteRe-inject a prompt on a 5-field cron (local time), recurring or once. Bound to the session; survives resume. Jittered.

Hook events

PreToolUseBefore a tool call, before permission checks. Blockable — exit 2 stops the tool.
StopWhen the model is about to end the turn. Blockable — append a message and it keeps working. The test-run hook.
UserPromptSubmitOn send. Returned text is appended to context; blocked means the model is not called.
PostToolUse · PostToolUseFailure · PermissionRequest · PermissionResultObservation only.
SessionStart · SessionEnd · SessionHeartbeatstartup/resume · exit/archive · every 60 s only when configured.
SubagentStart · SubagentStop · TaskStarted · NotificationSubagent and background-task lifecycle; Notification matches e.g. task.completed.
TurnStarted · Interrupt · StopFailure · PreCompact · PostCompact · UserPromptQueuedObservation only. Interrupt fires instead of Stop when you press Esc.
exit 0 · 2 · otherAllow · block (stderr = reason) · allow (fail-open). Timeout and crash also allow.

MCP

command · url · transport: "sse"stdio child process · HTTP endpoint · legacy SSE. Entries in mcp.json under mcpServers.
env · cwd · headers · bearerTokenEnvVar · enabledPer-server options; OAuth via /mcp-config login.
enabledTools · disabledTools · startupTimeoutMs · toolTimeoutMsPer-server tool allow/deny and timeouts.
mcp__<server>__<tool>Tool naming; permission rules take * and **. Unmatched calls ask; YOLO approves them all.

Models

Aug 2026

The lineup

Kimi K3Flagship. 1M context, $3 / $15 per M (cache hit $0.30). Declares low / high / max effort.
Kimi K2.7 CodeThe coding model. 256k, $0.95 / $4 (hit $0.19). Thinking, image and video in, tool use.
Kimi K2.6 · K2.5256k. $0.95 / $4 · $0.60 / $3. Still in many pickers.
kimi-code/k3 · kimi-for-coding · -highspeedThe aliases a Kimi Code plan provisions under managed:kimi-code, billed against the plan quota.

Cost

Kimi Code planFrom about $19/month for the managed models and quota; the Platform key bills per token instead.
cache-hit inputA fifth of fresh input on K2.7 — the cache-expiry dialog exists to protect it.
open weightsK-series weights are published; run them on a Western host or your own hardware and nothing goes to Moonshot.
any providerThe CLI is model-agnostic: Anthropic, OpenAI, Google, Vertex, or any OpenAI-compatible URL.

Don't

10 traps

Setup

the other `kimi`Two products install a binary called kimi. You want @moonshot-ai/kimi-code and ~/.kimi-code/; kimi migrate handles the old one.
"kimi: not found" in a scriptThe installer edits your shell profile; non-login shells and IDE-launched processes do not see it. Use the absolute path.
exporting KIMI_API_KEYCredentials come only from config.toml (or its [env] table, or KIMI_MODEL_*). The shell variable is ignored.
skipping /init"It ignores my conventions" — it never had them. /init, then prune.

Autonomy

a hook as the only guardHooks fail open. A deny permission rule or an agent tools list is the real barrier.
--auto in a repo you just clonedIt never asks — including about .env and SSH keys. YOLO at most; deny rules first.
a goal without a finish line"Find all bugs" blocks or runs forever. Name the evidence and the stop condition.
swarming dependent workItems must be independent; the template must carry the verification step.
trusting a cloned repo's .kimi-code/Project agents can override the main agent; project MCP servers run commands on start. Read, then trust.

Cost & data

K3 for grepPut explore and swarm workers on the cheap alias via [secondary_model]; spend K3 on the hard subtask.
code that cannot leave the buildingThe hosted service is under PRC jurisdiction. Self-host the open weights or use a Western inference host through [providers].
moonshotai.github.io/kimi-code · github.com/MoonshotAI/kimi-code · August 2026