Kimi Plugin: Work with Kimi in Claude Code and Codex

Kimi is a regular collaborator in the author's reasoning, writing, coding, and sustained project work. The main motivation is diversity of perspective: Kimi often notices different things and develops another approach. The plugin brings that collaboration into an existing workspace. You can begin an inquiry with Kimi, delegate implementation, or invite review.

For a starting pattern, see let Kimi frame the problem. Kimi models, the native Kimi Code workspace, and this plugin have different roles; the access guide separates them.

Kimi Plugin gives you several distinct moves:

• /kimi:review — Kimi reads your working-tree diff and returns plain Markdown findings with severity, confidence, and file:line references. Use when you've just made a change and want a sanity check before committing.
• /kimi:challenge — Adversarial pass. Kimi argues against your approach instead of polishing it. Useful for analysis scripts where the failure mode is "looks right, was wrong."
• /kimi:ask — Free-form Q&A delegated to Kimi. "Explain this regression," "trace this data flow," "what's the literature on X?" Useful when you want a fresh framing from a model trained on different data.
• /kimi:rescue — Full delegation: Kimi opens files, writes code, runs tests, reports back. Bounded by a plugin-side approval allowlist (no .git/ writes, no opaque package-manager scripts, symlink-aware path containment).
• /kimi:pursue — Experimental autonomous goal mode. Kimi works across continuation turns under a mandatory wall-clock budget, with the same write allowlist as rescue.
• /kimi:swarm — Parallel review fan-out. Read-only by default; --write uses a throwaway worktree and returns a reviewable patch rather than touching the user's real tree.

The plugin also installs seven subagents: kimi-rescue, kimi-review, kimi-challenge, kimi-ask, kimi-swarm, kimi-pursue, and kimi-swarm-write. The main Claude thread can dispatch these via the Agent tool when a task matches. The higher-blast-radius surfaces require explicit budgets and keep the same hook-level safety boundaries as the slash commands.

The plugin is a thin shell. The work happens in a local Node runtime.

/kimi:review "check the auth flow"
             |
             v
      companion runtime
             |
             +-- spawn kimi-code
             +-- tag run mode
             +-- capture event stream
             +-- enforce read-only policy
             +-- persist job history
             |
             v
      plain Markdown result

Subprocess-first transport. The plugin drives kimi-code as one kimi -p subprocess per job and consumes its stream-json output. The current plugin runs native agent-core-v2 with exact-version certification for Kimi Code CLI 2.5.0, 2.5.1 and 2.5.2. The upstream README still recommends 2.4.1; newer certification does not by itself replace that recommendation. The certified list also includes 2.4.1, 2.4.0, 2.3.3, 2.3.2, 2.3.1, 2.3.0 and older versions listed upstream. Earlier certified versions remain listed in the upstream runtime table. An unlisted patch or minor is refused before spawn with KIMI_CAPABILITY_NOT_CERTIFIED. An explicitly pinned kimi-code 0.2.0–0.41.x binary still uses the legacy-v1 path. The older Python Kimi CLI Wire transport remains available at the v0.4 tag.

For swarm on the earlier certified CLI 2.3.2 through 2.4.1, activation and deactivation briefly run authenticated loopback kimi web processes. One kimi -p -r subprocess still performs the task. Activation counts against the budget; the token stays in memory and out of logs. Cleanup failure prevents success. Older certified versions use kimi -p directly.

Upgrading from pre-1.10 sessions to native v2 requires fresh sessions. Old jobs remain available through status, result, and replay, but cannot be resumed on the native-v2 engine. Native v2 also refuses default_plan_mode = true, unsafe experimental settings, and Kimi flags in launcher-prefix arguments. These are version or configuration refusals, not hook-install failures; rerunning setup does not clear them. See the upstream compatibility and migration guidance (opens in a new tab) for the exact remedies.

Kimi Code session titles. Plugin sessions appear in the shared Kimi Code Desktop and kimi web history. New native-v2 sessions receive a readable fallback title that Kimi can replace with a generated title. Titles you set yourself are preserved.

Daily monitor reports. Upstream compatibility is now watched by a local monitor in the plugin repo. Monitor reports are continuity signals, not release gates: a new native-v2 kimi-code version still needs a source audit and real-binary smoke before the exact certification list moves.

The v1.9.12 durability pass also records engine provenance for every new model job: the operation, intended and observed engine, exact command tuple, probed version, certification source, and resume lineage. Rescue, pursue, and write-swarm derive their trusted workspace root from plugin-owned state rather than the upstream payload; an engine mismatch fails closed before work continues.

Hook-level safety. kimi-code -p mode auto-approves tool calls, so the plugin's real boundary is the PreToolUse block /kimi:setup installs. Model-spawning commands refuse to start without it; the review gate skips visibly rather than running unenforced.

• Claude Code and Codex each own a block in the shared ~/.kimi-code/config.toml; setup in one never touches the other.
• Setup validates the TOML and the hook script before writing, behind a private lock, so malformed config or concurrent setups fail safely rather than dropping enforcement.
• It probes the block directly and through /bin/sh -c, so GUI-launched PATH problems surface before a job runs.
• Read-only commands deny writes at the hook. Rescue, pursue and write-swarm add a quote-aware workspace allowlist and refuse git mutation.
• Write-swarm also refuses to start without a compatible kimi-code, and waits for teardown before returning, so it never removes its worktree mid-write.
• kimi-code 0.31 discovers project agent profiles under .kimi-code/agents and .agents/agents. Inspect those files before using a write-capable command in an untrusted repository; they can redirect the agent's instructions even though they cannot change the hook or the plugin's write allowlist.

Retryable hook-install refusals now carry a one-retry recovery protocol: the caller runs the resolved setup command and retries only after setup succeeds. Authentication is deliberately separate: a logged-out kimi-code reports an authentication refusal and needs kimi login, and rerunning setup does not repair it. Startup failures also preserve their underlying cause in the job record instead of collapsing to generic advice.

Patch-only write swarm. /kimi:swarm --write runs coordinator and coder subagents inside an ephemeral git worktree based on HEAD, serializes writes by default, and returns a .patch for the human or main agent to review. The plugin does not apply or commit the patch.

Zero native dependencies. Uses Node 22.5's built-in node:sqlite: no better-sqlite3, no node-gyp, no compilation step. dist/ is precompiled and committed; installed plugins work immediately with just node on PATH.

Codex packaging. The Codex plugin lives in a self-contained subfolder with its own manifest, skills, scripts, and mirrored runtime bytes. That separation prevents Claude Code from auto-discovering Codex-only skills at the repo root while still letting Codex install the plugin from the same repository marketplace.

Jobs retain a SQLite record and stream-json diagnostics. A session ID can come from stream metadata on native-v2 or anchored stderr on legacy-v1. After a native-v2 budget timeout, bounded recovery may identify one matching session-store journal. JSON results report kimi_session_id_source and recovery diagnostics where available. An ID is not guaranteed, and an absent ID does not prove that no upstream session was created.

Every model-spawning command runs under a wall-clock budget, so model-launched work cannot run indefinitely. Ask, review, and challenge default to 30 minutes and rescue to 45; --budget sets a per-job ceiling of up to 24 hours, a resume inherits it unless overridden, and backgrounding does not extend it. A budget timeout fails the job; for ask, review, challenge and rescue it keeps any settled partial answer, labeled as not a final answer. Cancellation keeps none. Every companion subcommand accepts --help.

Pursue and swarm do not expose a --background runtime flag, but an agent can detach the shell call when the run may outlast its foreground timeout. Stop a run with /kimi:cancel; without an ID it targets the latest running job for the current repository. Cancellation stops further pursue work but does not roll back edits already made in the real tree. For write-swarm, prefer cancellation to an interrupt so teardown can preserve the partial patch.

Beyond explicit commands, the plugin ships one opt-in hook: a Stop-time gate that runs whenever Claude is about to stop and decides whether to invite a Kimi review first.

This addresses a specific failure mode in long sessions: Claude declares "done" while a subtle issue remains. The gate gives a different model the last word on whether the work actually holds up before the session closes. Disable it for fast iteration; enable it for anything you'd be embarrassed to merge.

The pattern is portable even where the plugin is not: delegate to a structurally different model, and allowlist its writes. How it works sketches the subprocess and hook architecture for anyone recreating it elsewhere.

# Inside a Claude Code session
/plugin marketplace add linxule/kimi-plugin-cc
/plugin install kimi@kimi-marketplace
/kimi:setup

git clone https://github.com/linxule/kimi-plugin-cc ~/kimi-plugin-cc
claude --plugin-dir ~/kimi-plugin-cc

codex plugin marketplace add linxule/kimi-plugin-cc
codex plugin add kimi@kimi-marketplace

Bundled MCP interface

The plugin bundles seven model tools: kimi_ask, kimi_review, kimi_challenge, kimi_rescue, kimi_pursue, kimi_swarm, and kimi_swarm_write. The existing host setup and managed safety hook remain required.

Claude Code returns durable MCP tasks for task-capable calls; poll with tasks/get or cancel with tasks/cancel. Codex uses ordinary MCP results: a running job returns a handle for kimi_job_status, kimi_job_result, or kimi_job_cancel. A failed job returns an error with its artifacts.

Claude supplies its project directory. Without a host default, as is normal for Codex, give the initial operation an absolute workspace path. Later job-control calls use the persisted binding. Disconnecting the MCP server does not cancel jobs. These are source and package contracts, not a new interoperability test in every host.

Optional npm distribution

The marketplace commands above remain the default for Claude Code and Codex. The same release is also published as kimi-plugin-cc on npm (opens in a new tab) for an explicitly versioned local Claude Code install:

npm install --prefix ~/.local/share/kimi-plugin-cc kimi-plugin-cc@2.5.6
claude --plugin-dir ~/.local/share/kimi-plugin-cc/node_modules/kimi-plugin-cc

Run /kimi:setup, then /kimi:setup --check. Use one installation per host; do not load the local copy alongside an enabled marketplace copy. The package is the plugin, not a replacement for the upstream kimi executable.

After upgrading the plugin, rerun /kimi:setup for Claude Code or $kimi-setup for Codex once on that host. This repins the version-stamped plugin cache and verifies the managed hook before the next model-spawning command.

Choosing a model

Version 2.2.1 adds --thinking <effort> for a per-run request without changing the saved default. The runtime records the requested effort; a provider or model may ignore it. The same release adds hook-escape detection: a denied-policy call with a missing or different denial result produces diagnostic evidence, not proof that a write occurred. The monitor does not stop the run or fail the job. Enforcement still depends on the managed hook and its preflight checks.

Fresh sessions start with the model configured in Kimi. Run /kimi:setup --models, or ask Codex's $kimi-setup to list configured models, before selecting another. This reads the local inventory; it does not contact providers or prove that an account can access a model.

Pass a listed alias with -m for one task. A resumed session keeps its previous model unless you override it; a swarm override selects the coordinator, while Kimi's secondary-model settings can select its children. To change the saved default, use /model inside native kimi. Subscription login and API-provider setup belong in Kimi's /login and /provider, not in Claude Code or Codex's own authentication.

Prerequisites

• Certified Kimi Code CLI on PATH (2.5.0, 2.5.1 and 2.5.2 are now certified; 2.4.1 and earlier listed versions remain supported) — the plugin spawns kimi -p; set KIMI_PLUGIN_CC_KIMI_BIN to override the binary location.
• macOS or Linux. Windows is not currently supported by the plugin.
• Node ≥ 22.5 — for built-in node:sqlite. Set KIMI_PLUGIN_CC_NODE_BIN to override.
• bun is used only for contributor tooling. It is not required at runtime.

Removing the hook block

/kimi:setup --uninstall removes only the current host's block from ~/.kimi-code/config.toml. Use /kimi:setup --uninstall --all to remove every host's block from the shared config.

A literature-pipeline scenario. You're iterating on a Python script that extracts and deduplicates DOIs from a corpus of PDFs. After a long Claude session you've got working code, but the test coverage feels thin.

/kimi:review "review my last commit, focus on edge cases the tests miss"

Kimi reads the diff and returns Markdown findings with file:line precision. For example, it might flag three issues, one high-severity (DOI regex misses ArXiv-style IDs). The plugin reserves JSON for the opt-in stop-time review gate, not the ordinary /kimi:review command.

/kimi:rescue "fix the top finding from the last review"

Kimi opens the file, writes the fix, runs the relevant tests (allowlisted invocations only), and reports back. The job persists. If you restart Claude Code, /kimi:rescue --resume picks up where it left off.

If you want adversarial pressure on the approach rather than the code:

/kimi:challenge "is deduplicating by DOI the right primary key here, or am I missing edge cases that argue for a fuzzy match?"

Kimi argues against your design instead of polishing it.

For a broad, read-only audit across many independent files:

/kimi:swarm --budget 20m --max-concurrency 4 "fan out a review across the import pipeline modules"

For a multi-file edit fan-out, add --write; the plugin confines edits to a throwaway worktree and returns a patch for review.

The plugin sits alongside:

• Vox MCP — multi-model gateway when you want a one-shot consult rather than a full job lifecycle. Use Vox for quick questions, Kimi Plugin for review/delegation.
• Memex Plugin — captures the context of multi-model collaboration so future sessions know which model said what and why.
• Interpretive Orchestration — when qualitative analysis needs structured multi-model triangulation, the orchestration plugin uses Vox MCP for diverse perspectives in a single command. Kimi Plugin is the lighter-weight, code-and-text version of the same instinct.