Use Kimi Code with crystl

Updated October 1, 2026

Kimi Code is Moonshot AI’s terminal coding agent. crystl runs it, supervises its tool calls with real approval cards, and manages its shard. The rest of the integration is partial, and the gaps are large enough to read first rather than discover later.

Start here. Kimi gets approval cards, and a deny really stops the tool. It has no transcript reader and no resume, so there is no turn-end status, no history search, no chat dock, and no resurrect. Everything below says which of those matter and when.

1. Install Kimi Code

curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash

The script downloads the latest release, checks it, and puts kimi on your PATH. It does not need Node.js.

npm works too:

npm install -g @moonshot-ai/kimi-code

2. Log in

Run it from your project directory, then use its own login command:

kimi
/login

Pick either the Kimi Code device-code flow or a Kimi Platform API key.

3. Check it runs on its own

kimi --version

4. Launch it in crystl

Type it in a shard:

kimi

crystl spots kimi in the process tree and shows it as that shard’s agent. It is not in the agent pickers, and it has no settings tab, so typing the binary is the way in.

Do not expect an opening prompt to work. Kimi’s -p / --prompt flag runs one prompt non-interactively and then exits, which would end the session rather than start it, so crystl deliberately does not use it. Launch bare and type your first message into Kimi’s own interface.

What crystl can do with it

  • It manages the shard. Gems, shards, splits, scrollback, renaming, formations, and the workbench all work, because none of them need the agent’s cooperation.
  • It shows the agent and a working state. The shard reports Kimi as its agent, and crystl infers busy or idle by watching the process.
  • It raises real approval cards. Kimi’s tool calls go through the same approval modes and the same floating cards as Claude Code’s, through a blocking hook crystl merges into ~/.kimi-code/config.toml. It is on by default, and a deny really stops the tool: Kimi tells the model the call was refused.

What the card can and cannot do for Kimi

Three differences, all of them Kimi’s own shape rather than choices crystl made:

  • Allow releases the hold; it does not pre-approve. Kimi’s hook contract acts on a deny and nothing else, so after you click allow Kimi applies its own permission policy and may still prompt in its terminal. crystl notices that case and raises a notification saying the question is in Kimi’s own window and has to be answered there.
  • Always behaves as allow-once. Kimi has no channel for writing a permission rule back, so the next identical call asks again. crystl will not write rules into Kimi’s config from a card.
  • The hold lasts under ten minutes and fails open. Kimi caps a hook at 600 seconds, so crystl ends its own wait at 570, takes the card down, and raises a notification saying it has stopped watching. The same notification covers a bridge that is unreachable. A card nobody answers means the tool runs, so a long wait is worth a glance rather than a walk away.

One setup trap: Kimi reads KIMI_CODE_HOME before ~/.kimi-code, and crystl only sees that variable if it was set in the environment crystl itself launched with. Export it in your shell alone and the hooks land in ~/.kimi-code while Kimi reads elsewhere. Nothing breaks, the cards just never appear. kimi doctor names the file it actually read.

What it does not do

  • No turn-end reporting. crystl registers no lifecycle hook for Kimi, so its shard rows stay a plain idle, never ✓ declared done or ❓ needs you. A quiet Kimi shard proves nothing: it may be mid-task, finished, or waiting on you. A fanned-out Kimi worker reports done when its process exits, and vigil treats its idle reading as a guess.
  • No history, chat dock, or timeline. crystl ships no transcript reader for Kimi and will not guess at another agent’s format. Kimi does keep its own sessions under ~/.kimi-code/sessions; the format is undocumented and Moonshot warns against depending on it, so crystl names the location rather than reading it.
  • No resume or resurrect. Kimi’s own resume is scoped to a directory or an interactive picker rather than keyed on an id crystl holds, so closing the shard ends it.

Tool calls are supervised, so a fanned-out Kimi worker cannot do something risky behind your back. What you lose on a walk-away is the reporting: no turn-end status, no transcript to read afterwards, and no resurrect if you close the shard. It is a good choice for a shard you are sitting in front of, and a thin one for work you want to review later.

Model sizes

Kimi takes a model with --model (or -m). crystl pins no default, deliberately, so Kimi falls through to default_model in ~/.kimi-code/config.toml and uses your own configuration.

Ids that resolve on a stock install: kimi-k3, kimi-k2.6, kimi-k2.5, and kimi-for-coding. Your config.toml may define shorter aliases of its own.

crystl agent profile set --agent kimi --small kimi-k2.5 --standard kimi-k2.6 --large kimi-k3

See model sizes.

Troubleshooting

The shard shows no agent. crystl matches kimi and kimi-code in the process tree. A wrapper script or an alias that launches it under another process name hides it.

A worker never reports done mid-run. It cannot: crystl has no lifecycle hook for Kimi. The process exiting is the signal, which crystl wait done already uses.

No approval cards appear. Check kimi doctor for the config file Kimi actually read. If it is not ~/.kimi-code/config.toml, you have KIMI_CODE_HOME set in your shell rather than in crystl’s environment, and the hooks were written to the wrong place. Also check that Kimi is enabled in settings, agents.

Other agent setup