---
title: Kimi Code Provider
---

# Kimi Code Provider

## What it is

Omniscio can spawn Claude-Code-style sessions backed by **Kimi Code** — Moonshot's own agentic coding CLI (`kimi`) — as an alternative provider, alongside `claude` (the default), `codex`, `gemini`, `hermes`, `cursor` and the rest. Kimi Code runs on **its own login** (`kimi login`: Kimi Code OAuth or a Moonshot key you give the CLI), so a Kimi Code session is "Moonshot's agent on your own account," not Claude in a different harness.

**Kimi Code is not Kimi.** The **Kimi** provider ([kimi-provider.md](kimi-provider.md)) runs the Kimi *model* inside the Claude Code CLI against Moonshot's Anthropic-compatible endpoint, with an API key Omniscio stores. **Kimi Code** is Moonshot's *own* CLI agent driven over the Agent Client Protocol (ACP); Omniscio stores no key for it. They are two providers in the picker (`kimi` and `kimicode`) and can both be enabled.

### What the user sees

A Kimi Code session looks the same as a Claude session in the sidebar and main pane — same status dots, same streaming bubbles, same Ctrl+Enter to send. The differences:

- **Kimi Code mark** in the session header next to the title (monochrome, by brand), like Codex. Kimi Code is a **first-class** provider — it shows a badge, is a per-project default, and is switch-to-able. It sits last in the picker order.
- **Token-by-token streaming.** Omniscio drives a kept-alive `kimi acp` child over JSON-RPC/NDJSON on stdio (the shared ACP layer), so the reply appears as it generates; one final push replaces the bubble with the full text when the turn completes.
- **Real stateful multi-turn.** The ACP session lives in the child, so the agent remembers the whole conversation without Omniscio replaying prior turns.
- **A longer first-response window.** Kimi Code plans server-side before its first output, so the "no response yet" nag waits 120s instead of the 30s default before it says the agent may still be working.
- **Images go straight to the agent when your Kimi Code build can read them.** On start-up Omniscio asks the running `kimi acp` child whether it accepts image prompts; if it does, an attached image is sent inline as an ACP image block. If it does not, the image is not sent and the session shows a short note saying so — describe the image in words, or switch to an engine with image support — never a silent drop. Documents are not delivered to Kimi Code (the compose area warns before you send).
- **Your project's MCP servers are handed to Kimi Code** when its session starts, through the same shared ACP layer Gemini and Hermes use; remote (HTTP) servers only when the child said it supports that transport. If Kimi Code refuses to start with the servers, Omniscio starts it once more without them and tells you in the session.
- **No per-session dollar cost.** Kimi Code emits no token/cost over ACP v1, so Omniscio shows turn counts but the cost line reads "not reported." Your spend lives in your Moonshot / Kimi Code account.
- **Optional model pick.** When a session carries a model id, Omniscio passes it as `kimi acp --model <id>`; otherwise Kimi Code runs its own default.

## Where to find it

### How to enable

> **Master toggle required first.** Kimi Code is an alternative provider — by default Omniscio ships as a Claude-only product, and the whole Kimi Code setup section is hidden in Settings → Accounts. Flip **Settings → Accounts → Show alternative AI providers** to ON (off by default) and the **Kimi Code (CLI provider)** card appears. With the master off, the per-launch provider switcher hides Kimi Code. Your "Allow Kimi Code sessions" toggle is preserved across master-toggle flips.

Two gates must both pass (`getProviderSpawnReadiness` enforces them in this order) — **no API-key gate** (Kimi Code holds its own login):

1. **Kimi Code CLI binary** — the `kimi` binary must be installed. Omniscio **detects** it on PATH but does not install it; the card's Install link opens Moonshot's install docs. Install it, then run **`kimi login`** (or `kimi` and `/login`) to sign in. If you just installed it, **restart Omniscio** so the running process picks up your updated PATH.
2. **Allow Kimi Code sessions** toggle — off by default. Same security stance as the other auto-running providers: enable it only because you intend to use it.

Once both are green, you launch a Kimi Code session three ways:

- **Per-project default** — the Edit-Project "Default provider" radios and the "+ New Session" split-button include Kimi Code.
- **Per-launch override** — on a fresh (zero-message) session, the **Change-provider button** lets you pick Kimi Code before the first message. A not-ready provider appears disabled with an "Install…" suffix that deep-links into the relevant Settings panel.
- **Programmatically** — anything that creates a session with `provider: 'kimicode'` (recipes, the CLI control server, deep-links). The same two readiness gates apply on the backend.

## How it behaves

### No virtual project

Kimi Code has **no dedicated sidebar entry** (unlike `__codex__` / `__gemini__` / `__antigravity__`), so the "Allow Kimi Code sessions" toggle always applies. You spawn Kimi Code inside any real project — the same posture as Hermes, Cursor and OpenCode.

### Error states and fixes

Two gap codes (no key gap — Kimi Code uses its own login):

| Gap              | What it means                                 | Click-to-fix lands you at…                            |
| ---------------- | --------------------------------------------- | ----------------------------------------------------- |
| `toggle-off`     | "Allow Kimi Code sessions" is OFF in Settings | Settings → Accounts → Allow Kimi Code sessions toggle |
| `binary-missing` | `kimi` CLI not found                          | Settings → Accounts → Kimi Code CLI card              |

If a turn fails after Kimi Code is found, the most common cause is a missing login — the message says to run `kimi` in a terminal and use `/login`, then try again. A slow cold start that misses the handshake window is retried once with a fresh child before it is reported.

If a turn is rejected because Kimi Code's own working memory outgrew the model's window (usually a command that printed a huge amount of output), the message says it ran out of room and that the conversation is saved. Omniscio has already replaced the overflowed `kimi acp` process, so your next message starts fresh on a compact copy of the conversation — usually no new session is needed. If it still runs out of room, the conversation may be too long for the model, so start a new session.

## For agents

### How it works under the hood

**Kept-alive ACP child per session.** Omniscio spawns `kimi acp` once (the subcommand form — not a flag like Gemini's `--acp`) and keeps it alive for the session's lifetime. The child starts **lazily** on the first message, so creating or switching to a Kimi Code session is instant. On an app restart the manager re-registers and re-spawns a fresh child on the next message.

**One config subclass over the shared slim base.** `KimiAcpSessionManager` is a ~40-line config subclass of `SlimAcpSessionManager` (shared with Hermes): it supplies the `KimiAcpClient` factory, the handshake-timeout predicate and its strings. The whole turn / message / event body — and the images and MCP delivery below — lives once on the base; a guard test fails the build if a slim subclass overrides a lifecycle method.

**Abilities are discovered, not assumed.** The shared ACP client performs the `initialize` handshake once and keeps what the child advertised (`promptCapabilities.image`, `mcpCapabilities.http` / `sse`, auth methods). The registry's `images: true` / `mcp: true` are ceilings: an image is sent inline only when the child advertised image prompts (otherwise it is withheld and a visible note names the engine), and the project's resolved MCP servers ride `session/new` through the shared in-band connector — remote HTTP servers only when the child advertised that transport, with one retry without servers (and a visible note) if the child refuses to start with them.

**Auth stays in Kimi Code's own login.** Omniscio spawns with a clean environment (`buildCleanSpawnEnv()`) — no key is injected, so no ambient credential can silently hijack billing. A `session/new` auth failure is humanized to "run `kimi` and use `/login`"; Omniscio does not attempt an ACP `authenticate` call (Kimi's auth method ids are undocumented in v1).

**Permission requests — v1 auto-approve.** The permission handler auto-approves tool calls (`allow`), the same documented v1 posture as Hermes. Adding the shared dangerous-path denylist net is a tracked hardening follow-up.

**Cost tracking.** Kimi Code ACP v1 exposes no token/cost data (`costReporting: 'none'`), so cost stays a structural zero surfaced as "not reported"; `numTurns` is bumped per turn so the sidebar's blank-session filter keeps the session visible.

**Interrupt.** Stop sends an ACP `session/cancel` notification and authoritatively concludes the turn in the manager; partial streamed text is preserved and status returns to `ready`.

**Routing.** A launch (and every later send / interrupt / terminate / change-provider) with `provider: 'kimicode'` reaches `kimicodeAcpSessionManager` through the dispatch maps derived from its ONE entry in `engine-registrations.ts`; the same entry supplies its send route (`makeAcpSendStrategy`). The `sessions.provider` validation triggers refresh from the provider registry at boot, so the id needs no dedicated migration. `restartResumable: false` keeps Kimi Code out of the crash/restart-resume nets (no re-attach verified yet).

### Files

- [src/main/services/engines/kimicode-acp-session-manager.ts](../../src/main/services/engines/kimicode-acp-session-manager.ts) — the config subclass of [slim-acp-session-manager.ts](../../src/main/services/engines/slim-acp-session-manager.ts) (singleton `kimicodeAcpSessionManager`)
- [src/main/process/kimi-acp-client.ts](../../src/main/process/kimi-acp-client.ts) — spawns `kimi acp [--model <id>]` and drives `session/new` / `session/prompt` / `session/cancel` / graceful stop over the shared `SlimAcpSessionClient`, which performs the one ACP `initialize` handshake ([acp-capabilities.ts](../../src/main/process/acp-capabilities.ts) reads what it kept)
- [src/main/services/engines/kimicode-binary-resolver.ts](../../src/main/services/engines/kimicode-binary-resolver.ts) — the `kimi` resolver, derived from the setup catalog
- [src/shared/providers/provider-setup-catalog.ts](../../src/shared/providers/provider-setup-catalog.ts) + [src/main/services/providers/main-registry.ts](../../src/main/services/providers/main-registry.ts) — `binary-login` setup row; readiness derives from it (`deriveStandardReadiness('kimicode')`: toggle + binary, no key)
- [src/shared/providers/registry.ts](../../src/shared/providers/registry.ts) — the `kimicode` descriptor (`runtimeKind: 'persistent-external'`, `images: true`, `mcp: true`, `restartResumable: false`, `costReporting: 'none'`, `pickerOrder: 15`)
- [src/main/services/providers/engine-registrations.ts](../../src/main/services/providers/engine-registrations.ts) — its ONE registration (manager + `makeAcpSendStrategy`)
- [src/main/services/session/persistent-external-send-strategy-factories.ts](../../src/main/services/session/persistent-external-send-strategy-factories.ts) — `makeAcpSendStrategy`: images forwarded only when the child advertised them; the discovered answer overrides the media table for the image bridge
- [src/renderer/src/components/ui/KimicodeIcon.tsx](../../src/renderer/src/components/ui/KimicodeIcon.tsx) — the brand glyph the badge and picker use
- [tests/unit/process/kimi-acp-client.test.ts](../../tests/unit/process/kimi-acp-client.test.ts) · [tests/unit/services/kimicode-acp-session-manager.test.ts](../../tests/unit/services/kimicode-acp-session-manager.test.ts) · [tests/unit/services/slim-acp-session-manager.test.ts](../../tests/unit/services/slim-acp-session-manager.test.ts) — the client, the twin's lifecycle contract, and the shared base's images + MCP delivery

### Comparison with other providers

| Concern             | Kimi Code                                                   | Hermes                                   | Gemini                                    |
| ------------------- | ----------------------------------------------------------- | ---------------------------------------- | ----------------------------------------- |
| Auth                | Kimi Code's own login (`kimi login`)                        | Hermes's own config (`hermes setup`)     | Google sign-in or API key                 |
| Underlying model    | Kimi Code default, or `--model <id>` per session            | Your choice (`hermes setup`)             | Gemini                                    |
| Process model       | Persistent `kimi acp` child (ACP)                           | Persistent `hermes acp` child (ACP)      | Persistent `gemini --acp` child (ACP)     |
| Multi-turn memory   | **Native** (ACP session)                                    | **Native** (ACP session)                 | **Native** (ACP session)                  |
| Images              | Inline ACP blocks when advertised, else a visible note      | Same (shared slim ACP base)              | Inline ACP blocks                         |
| MCP servers         | Project servers on `session/new` when advertised            | Same (shared slim ACP base)              | Yes (in-band connector)                   |
| Cost emitted        | **No** (not reported)                                       | **No** (records $0)                      | **No** (Google-billed)                    |
| Readiness gates     | **2** (toggle + binary, no key)                             | **2** (toggle + binary, no key)          | 3 (toggle + binary + key)                 |
| `restartResumable`  | `false`                                                     | `false`                                  | N/A (has its own `--resume <uuid>`)       |

## Related

- [hermes-provider.md](hermes-provider.md) — its slim-ACP twin: same base, same gates, same handshake-gated abilities
- [kimi-provider.md](kimi-provider.md) — the Kimi MODEL through the Claude CLI; a different provider with an API key
- [switching-providers.md](switching-providers.md) — enabling alternative providers and the per-session picker
- [chat-attachments-part-2.md](chat-attachments-part-2.md) — how each engine family receives attachments
- [ai-providers.md](ai-providers.md) — the cross-provider overview