Kimi Code — the 2026 Method

00Start here

Most Kimi Code write-ups — it has existed in this form only since a June 2026 rewrite — are "the cheap Claude Code" comparisons: install it, notice it reads your AGENTS.md, notice the price, move on. True as far as it goes, and it misses the two things the tool does differently.

The first is goals. Every agent can take a prompt that says what to do next; Kimi's /goal takes an objective that says what must become true, then keeps working turn after turn until it is — or until it can say precisely why it is blocked. The second is swarms: one prompt template, a list of items, one subagent per item in parallel, with a live progress card. Between them they cover the two shapes most real work takes: a finish line you can name, and a pile of similar things.

Around those sit the now-standard pieces — skills, custom agents, hooks, MCP, plugins, plan mode, a local web UI and an ACP server on the same engine — and a model that costs a fraction of the frontier labs' while sitting at the top of the open-weight tier for agentic coding.

Three statements anchor the method:

On goals: "Unlike a normal prompt that says what to do next, a goal says what must become true. Use /goal when the task has a clear finish line, but the next useful step depends on what the agent learns while it works."

Kimi Code documentation, Goals

On hooks: "Precisely because of fail-open, Hooks are suitable for alerts and lightweight interception, but should not be used as the sole security barrier."

Kimi Code documentation, Hooks

On what it already reads: /import-from-cc-codex — "Import Claude Code and Codex instructions, skills, and MCP settings into Kimi Code." There is nothing to port before the first useful session.

Kimi Code built-in skills

Everything below follows from those: describe outcomes rather than steps, put the hard guarantees in permission rules rather than scripts, and reuse the configuration you already have.

01Audit your own setup first

Before any technique, check what you have. The install script puts kimi in ~/.kimi-code/bin/ and edits your shell profile, which means it is not on the PATH in non-interactive shells — scripts, cron, IDE-launched processes. That is the first thing to know.

~/.kimi-code/bin/kimi --version        # 0.38.0 or later; it ships several times a week
kimi doctor                           # config.toml and tui.toml valid?
kimi provider list                    # which providers and models are configured
ls ~/.kimi-code/skills ~/.kimi-code/agents ~/.agents/skills ~/.agents/agents
ls .kimi-code/skills .kimi-code/agents .agents/ AGENTS.md 2>/dev/null
grep -c '^\[\[permission.rules\]\]' ~/.kimi-code/config.toml   # any hard rules?
grep -c '^\[\[hooks\]\]' ~/.kimi-code/config.toml

Inside a session: /status (model, mode, cwd), /usage (tokens and quota), /mcp, /plugins list.

02The four shifts

Prompts → goals

The old loop: prompt, read the result, prompt again. The new loop: state the finish line and the evidence, and let the agent run until it holds. "Fix the failing checkout tests" is a prompt. "Every checkout test passes, each fix has a test, the suite runs green, stop if still blocked after 20 turns" is a goal. The difference is who decides the next step when the first clue is not the root cause.

Correcting in chat → writing rules

Covered above. This is the one that compounds — across vendors, because the instruction layer is portable.

Hooks → permission rules

Kimi's documentation is unusually frank: hooks fail open. A hook that errors, times out or returns the wrong exit code allows the call. So the structural guarantees live elsewhere — in [[permission.rules]] with decision = "deny", which survive every mode including headless, and in an agent's tools list, which is enforced before execution. Hooks are for the test run on Stop and for notifications.

One model → a pool

The main agent on K2.7 Code or K3; explore subagents and swarm workers on the cheap alias; the hard subtask on K3 at max effort. [secondary_model] makes that a configuration rather than a habit. That is section 09.

03Where the code goes — decide this first

Kimi is built by Moonshot AI in Beijing. That is the first thing anyone asks, so settle it before the first session rather than after.

The point that makes the decision tractable: the model is separable from the company. The K-series weights are published under a modified MIT licence, which is how they turn up on Western hosts and inside Copilot. The CLI's provider table takes any OpenAI-compatible endpoint — kimi provider catalog add or a [providers.x] block — so you keep the tooling and change where the tokens are processed. Routes three and four are what make Kimi usable at work at all; routes one and two are fine for what you would send to any cloud API.

Two smaller facts. Telemetry is on by default (telemetry = false). Sessions are stored locally under ~/.kimi-code/sessions/ as event streams that can contain tool output and credential traces — treat kimi export zips like logs, not like documents.

04Verification — the primary lever

The logic is simple. An agent stops when the work looks done. Without a check it can run, "looks done" is the only signal available — and you become the verification loop, at review time. Give it something that returns pass or fail and the loop closes on its own.

The ladder

Rung 4 matters because the agent that did the work is the worst judge of the work — models prefer their own output. A reviewer whose tools: list has no editor cannot "fix" what it finds and is enforced before execution, not just shown to the model. The kit's reviewer.md is exactly that; run it as kimi -p --agent reviewer "…" on the diff, or tell the main agent to delegate to it when done. For the strongest version, run the reviewer on a different vendor's model — the provider table makes that one config block.

Rewrite your prompts — as goals

✗  add retry logic to the client
✓  /goal HttpGateway.Send retries 5xx and timeouts with exponential
   backoff (max 3, jitter). Tests exist for: retries on 503, no retry
   on 400, gives up after 3. `npm test -- gateway` passes. Paste the
   summary. Stop if blocked after 15 turns.

✗  the build is broken
✓  `npm run build` fails with: [paste]. Fix the root cause — do not
   suppress the error or pin the package. Verify the build succeeds
   and paste the last 20 lines.

And always: ask for evidence, not assertions. "Paste the test output" beats "confirm it works." A goal that names the evidence is checked against it every turn; one that does not is checked against the model's opinion.

05Context is the budget

Performance degrades as the window fills. Kimi compacts automatically when the remaining window drops below [loop_control] reserved_context_size; set it, because the default of "when we have to" is late. K2.7's window is 256k; K3's is 1M, which moves the cliff but does not remove it.

Two rules of thumb

• After two failed corrections on the same issue, /undo past them or /new with a better brief. A clean context with a good prompt beats a long one full of failed approaches.
• Mind the cache-expiry dialog. Resume after a long idle and Kimi warns that the prompt cache has expired and offers to compact. Cached input on K2.7 is a fifth of the fresh price; the dialog exists to save you money. Say yes.

AGENTS.md discipline

Kimi reads the project AGENTS.md, a global ~/.kimi-code/AGENTS.md, and the cross-tool ~/.agents/AGENTS.md. /init writes the first one from the codebase — then prune it. The test for every line: "would removing this cause the agent to make a mistake?" Build, test and lint commands; conventions that differ from the default; architecture boundaries with the reason; known traps. Not the directory tour, not what the linter enforces.

06How to write a brief now

Delegation means full task context in turn one: goal, constraints, acceptance criteria. Think hard once rather than iterating fast.

GOAL        what "done" looks like, in one sentence — this becomes the /goal
CONTEXT     which files (@path); what pattern to follow
CONSTRAINTS what must not change; what is out of scope
VERIFY      the exact command, the expected result, and "paste the output"
STOP        the turn or token budget after which to report blocked

Plan mode — when it earns its place

Shift-Tab. The agent explores read-only and writes a plan; Write and Edit are restricted to the plan file; exiting needs your approval even in YOLO (only auto self-approves). ExitPlanMode can offer up to three alternative approaches for you to pick from — use that for "add authentication" or "add caching", the tasks with a real design choice. Skip it for the single-file fix; planning a task that did not need planning is pure latency.

Let the agent interview you

I want to build [one line]. Interview me before writing anything —
data model, failure cases, what must not change, tradeoffs I haven't
considered. Use AskUserQuestion. Don't ask obvious questions. When
we've covered everything, write SPEC.md and stop.

Then /new and execute the spec as a goal in a fresh session. Clean context, written reference, a finish line.

Three more techniques

• Challenge the output. "Prove this works — show me the diff and the test output." Then hand it to the reviewer agent.
• Show it, don't describe it. Ctrl-V pastes an image or a video — a screen recording of the bug, a walkthrough of the UI flow you want. Video input is a genuine Kimi distinction; use it.
• Stack skills in one prompt. Type / after whitespace to insert a second skill token; Kimi activates them together and one /undo reverts the whole submission.

07The parallelism ladder

Five rungs, each a different answer to "who holds the plan?"

Worktrees

git worktree add ../repo-ratelimit feature/ratelimit
cd ../repo-ratelimit && kimi -y --plan          # its own session, its own files
/title ratelimit-tests-green                   # name by outcome

Kimi does not manage worktrees for you; git worktree does, and a session per directory follows. Name them by outcome so /sessions reads as a status board.

Subagents — isolated, bounded, one level deep

Just append "use subagents" to a hard prompt, or name one: "use explore to map how auth handles token refresh before you change anything." Three built-ins — coder (read/write/run), explore (read-only), plan (no shell) — plus any agent file you write. Each has its own context; only the final message returns. Built-in subagents cannot spawn further subagents; fan out from the main agent, do not build trees. Each dispatch is an approval unless allowed; "always allow" choices propagate down. /tasks shows background ones working, with their model and effort.

---
name: reviewer
description: Read-only reviewer. Reports only correctness, security and
  stated-requirement findings; says plainly when the diff is sound.
tools: [Read, Grep, Glob, Bash]
disallowedTools: [Write, Edit]
---
You are reviewing a diff you did not write…

Swarm — the big one

/swarm write a unit test file for every module under src/billing/,
  following tests.instructions in AGENTS.md. Run each file's tests
  and include the summary in your final message.

The main agent turns that into an AgentSwarm call: one prompt_template with {{item}}, one subagent per item, in parallel, with rate-limit-aware retries and a progress card; results roll up into one message. It is the right tool when the items are genuinely independent and the wrong one when they are not — two items touching the same file are not independent, and you should say so. From manual mode it offers to switch to auto or yolo first, because approving forty subagents by hand is not a thing anyone does. Cap the ramp with KIMI_CODE_AGENT_SWARM_MAX_CONCURRENCY if the provider rate-limits.

Put the verification in the template. A swarm whose items each run their own check and report the result is a fleet of closed loops. One whose items just "write the tests" is forty plausible files.

The goal queue

/goal next <objective> queues a finish line the agent cannot see until the current one completes; /goal next manage reorders the queue. Three goals — make the suite green, then update the docs, then write the changelog — run to completion without a prompt between them, and the chain stops if any blocks.

08Making it permanent

Prefer the .agents/ directories. Kimi scans both its own .kimi-code/ tree and the generic .agents/ tree (project and user level), and the generic one is what other agents read too. A skill written once under ~/.agents/skills/ is a skill for every tool you own.

Skills

The rule of thumb: if you do something more than once a week, make it a skill. A skill is a folder — SKILL.md plus scripts and references — and its description and whenToUse are the matcher: what it does and when, or the model never reaches for it.

.agents/skills/release-notes/SKILL.md
---
name: release-notes
description: Draft release notes from merged PRs since the last tag.
whenToUse: when asked for release notes, a changelog entry, or "what shipped"
disableModelInvocation: true
arguments: [since]
---
1. `git describe --tags --abbrev=0` for the last tag (or use $since)
2. `gh pr list --state merged --search "merged:>$since" --json number,title,labels`
3. Group by label; one line per PR; link each. Write CHANGELOG.md; do not commit.

disableModelInvocation: true means only you can run it (/release-notes v1.2) — right for anything with side effects. $ARGUMENTS, $0, $since and ${KIMI_SKILL_DIR} expand in the body. /sub-skill.review proposes how to fold a sprawling skill set into parent/child bundles.

Permission rules — the floor

[[permission.rules]]
decision = "deny"
pattern  = "Bash(git push --force*)"
reason   = "never rewrite shared history"

[[permission.rules]]
decision = "deny"
pattern  = "Read(**/.env*)"

[[permission.rules]]
decision = "allow"
pattern  = "Bash(npm test*)"

Matched in order; patterns are Tool or Tool(arg-pattern); MCP tools match as mcp__server__*. Deny rules hold in YOLO, in auto, in -p, and inside subagents. This is where Grok users put a sandbox profile and Claude users put a hook; in Kimi it is the rule table.

Hooks — for the things that should happen, not the things that must not

[[hooks]]
event   = "Stop"
command = "~/.kimi-code/hooks/verify.sh"   # exit 2 → the model keeps working
timeout = 300

[[hooks]]
event   = "Notification"
matcher = "task\\.completed"
command = "terminal-notifier -title Kimi -message 'Task done'"

Event JSON on stdin; exit 0 allows, exit 2 blocks with stderr as the reason; anything else — including a crash or timeout — allows. Only PreToolUse, Stop and UserPromptSubmit can block at all. The Stop hook is the one worth having: it turns "I think I'm done" into "the suite says I'm done."

Sessions

kimi -c continues, kimi -S picks, /fork branches and puts a resume command on your clipboard, /title names. Sessions are event streams under ~/.kimi-code/sessions/; kimi vis replays one in a browser, which is the fastest way to understand what a long unattended run actually did.

09Models and cost — where to spend

Those are Platform API prices; a Kimi Code plan (from about $19/month) provisions kimi-code/k3, kimi-for-coding and a -highspeed variant against a quota instead, and /usage shows what is left. Either way the ratio is the point: K3 output costs nearly four times K2.7's, and cache-hit input is a fifth of fresh. Spend judgement on judgement; spend nothing on reading.

The model pool

# config.toml — requires KIMI_CODE_EXPERIMENTAL_SECONDARY_MODEL=1
[secondary_model]
default_model = "moonshot-ai/kimi-k2.6"
[secondary_model.models]
"moonshot-ai/kimi-k2.6" = "Fast and cheap — explore, swarm workers, small edits."
"moonshot-ai/k3"        = "Strong reasoning — pick for hard debugging or design."

With a pool configured, the Agent and AgentSwarm tools gain a model parameter and the main agent reads your hints to choose per spawn; force = true pins every subagent to the default instead. Register a second alias for the same model with [models."k3-max".overrides] default_effort = "max" and the pool carries effort as well as model. A swarm of cheap workers judged by one K3 reviewer costs a fraction of the all-K3 version and finds the same bugs.

10Web UI, IDE and headless

One engine, three front ends. The TUI is the default; the other two exist because some things a terminal does badly.

kimi web

A local server and a browser UI on the same engine: a session sidebar with Open / Done / Workspaces, a goal strip with a token-budget bar, swarm cards that stay open while workers run, Cmd-K search across sessions, and GET /openapi.json for the REST API if you want to drive it. /web from the TUI hands the current session across. It binds to loopback and prints a bearer token; --host opens it to the network, which you do only behind your own TLS proxy, and --dangerous-bypass-auth means exactly what it says.

kimi acp

The Agent Client Protocol over stdio — Zed natively, JetBrains through the AI chat plugin. The editor launches kimi acp as a subprocess and drives sessions and tool calls; MCP servers the editor declares are forwarded. GUI-launched processes do not inherit the shell PATH, so the config needs the absolute path: ~/.kimi-code/bin/kimi.

Kimi as a component

kimi -p "summarise the failing tests" < test.log
git diff main | kimi -p "list any change that alters a public API"
kimi -p --output-format stream-json "…"         # one JSON object per line
kimi -p --agent reviewer "review the diff on this branch"
kimi -p "/goal make `npm test` pass; stop if blocked after 20 turns"
                                                # exit 0 done · 3 blocked · 6 paused

-p runs under auto permission — nobody is there to approve — so the deny rules are the only floor. Pair a scheduled run with a read-only agent file (tools: [Read, Grep, Glob]) and [tools] disabled for anything it must not touch. Print mode stays alive while background tasks finish and feeds each completion back as a turn ([background] print_background_mode = "steer"); set "exit" for a pure one-shot. The goal exit codes make kimi -p "/goal …" a CI step that fails the pipeline when the finish line is not reached.

MCP

/mcp-config to add servers (stdio, HTTP, legacy SSE; OAuth via /mcp-config login), /mcp for status, mcp.json at user or project level. Two disciplines: every server costs context (its tool schemas load each session), and tool output is data, not instructions. A project-level mcp.json runs commands when a session starts — which is why the trust prompt lists them and defaults to Don't trust. Keep write-capable MCP tools out of YOLO sessions: it approves all of them.

11Beyond the repo — documents, data, the desktop

Step one — give it something to read

A plain-markdown wiki in git — decisions and why, runbooks, where things live, traps and the incident that proves them — and CLI access to live data, because pasting is stale, truncated and unrepeatable. @-reference a wiki page in the prompt and the agent loads it; --add-dir makes a second tree part of the workspace. None of this is Kimi-specific and all of it matters more than any setting above.

Step two — find the verification loop

Step three — write the domain knowledge down

Every domain has conventions an agent cannot guess. Each becomes an instruction line, a skill or a wiki page — written once. The most quietly valuable is a runbook skill with disableModelInvocation: true: the exact commands, the check at each step, the rollback — run by you, with the agent doing the typing.

12Away from the keyboard

The pattern that ties them together is the one from section 04: give the unattended run a way to know it is done — and, because -p runs under auto, a deny-rule floor under what it may do while nobody is watching. A scheduled goal without a named finish line is the one invocation on this page to refuse to write.

13Tools on the PATH

An agent is exactly as capable as the command-line tools it can call. Kimi cannot make a PDF or query a database by wanting to — it needs a binary on the PATH that does it and returns an exit code. It bundles its own rg and fd; the rest is on you.

Three selection rules. Prefer tools with a non-interactive mode — an agent cannot answer a prompt. Prefer machine-readable output (--json, exit codes). Prefer one tool that does a thing well over a GUI app with a CLI bolted on.

14The starter kit

Four files that turn the ideas above into configuration. Copy them into a repository's .agents/ (so other agents see them too) and your ~/.kimi-code/config.toml, and adapt.

15What to do, in order

This week — thirty minutes

• Decide the route in section 03 — hosted plan, or the weights elsewhere — and write it down.
• /login; /init in a real repository; prune the AGENTS.md it writes. If you have Claude Code config, /import-from-cc-codex first.
• Copy the kit's deny rules into config.toml. Then, and only then, kimi -y --plan on a real task.
• Write one /goal with a named finish line and watch it check itself after each turn.
• Next time you correct Kimi, stop and ask: should this be a rule instead? Then write it.

Next week

• Install the reviewer agent and make "have the reviewer check it" the last line of every brief.
• Install the Stop hook; break a test and watch it send the agent back.
• Enable the model pool and move explore onto the cheap alias; run /usage at the end of the week.
• One skill under ~/.agents/skills/ for the thing you do every Friday.
• On the next pile of similar things, /swarm it with the verification in the template.

The month after

• Queue three goals with /goal next and leave for the evening.
• Point a second [providers] block at another vendor and run the reviewer on it.
• Put a kimi -p "/goal …" on a schedule with a read-only agent and see whether you read the output.
• Try kimi web for a long swarm and kimi vis on a session you did not watch.
• Paste a screen recording of a bug instead of describing it.

16Anti-patterns

The one-paragraph version

Decide where the code goes before the first session — the hosted service is a jurisdiction choice, the open weights are not. Then give the agent a finish line instead of a next step: a goal that names the evidence, checked after every turn, with a stop condition in the text. Put the hard guarantees in deny rules and read-only tool lists, because hooks fail open; use hooks for the test run on Stop. Guard your context like a budget and take the cache dialog's advice. When Kimi gets something wrong, write a rule in AGENTS.md or ~/.agents/ rather than a correction in chat, so every agent you own improves at once. Put the reading on the cheap model and the judgement on K3. And when the work is bigger than one conversation, don't hold it in one: subagents for research and review, a swarm for the pile of similar things, a queue of goals for the evening.