msd-core/docs/migration/kimi-to-kimi-code.md

Migrating from --kimi to --kimi-code

When: you installed MSD via --kimi --global but you're actually running Kimi Code (Moonshot's Node CLI, ~/.kimi-code/config.toml), not Kimi CLI (Moonshot's Python CLI, ~/.kimi/config.toml).

Symptom

Before the Phase 1 descriptor split (epic #2505), MSD conflated both products under a single kimi runtime. If you ran --kimi --global on Kimi Code:

• msd-tools query agent-skills <name> returned empty (the Python kimi-cli agent YAMLs are inert on Kimi Code).

• Every workflow that called a named MSD subagent (msd-planner, msd-executor, …) failed at dispatch (Kimi Code only recognizes coder, explore, plan).

• Every MSD guard hook (the PreToolUse guards msd-prompt-guard, msd-read-guard, msd-worktree-path-guard, msd-workflow-guard, and the PostToolUse scanner msd-read-injection-scanner) was silently dormant (#2304) — the matcher was translated but the payload check wasn't, so the hooks exited 0 on every Kimi-vocabulary tool call.

  Scope after the fix (#2547): normalization makes each hook's checks run. It does not make all of them enforceable on Kimi. Only PreToolUse results are consulted by kimi-cli, so the enforceable blocks are the worktree cross-root write block and the workflow force-add block. msd-read-injection-scanner is PostToolUse, whose results kimi-cli discards, so its prompt-injection block does not apply on Kimi regardless of what it emits.

Which product am I on?

Check	Kimi CLI (Python)	Kimi Code (Node)
Config file	~/.kimi/config.toml	~/.kimi-code/config.toml (KIMI_CODE_HOME)
Built-in subagents	Custom via YAML (extend:, system_prompt_path)	Three only: coder, explore, plan
Skills discovery	~/.config/agents/skills or ~/.agents/skills	~/.kimi-code/skills/ (auto, merge_all_available_skills = true)
Language	Python (kimi-cli)	Node

If ~/.kimi-code/config.toml exists and ~/.kimi/config.toml does not, you're on Kimi Code.

Migration steps

1. Re-install with --kimi-code

npx @golem15/msd-core --kimi-code --global

This installs the correct Agent Skills surface at ~/.kimi-code/skills/msd-*/SKILL.md (Phase 2) and activates the Phase 0 guard normalization (the dormant-guard fix). The Phase 5 installer will warn you if you accidentally pick the wrong variant.

2. Remove inert Python-kimi-cli artifacts (if any)

If your prior --kimi install wrote agent YAMLs (the kimi-agents artifact layout) into your config dir, they're inert on Kimi Code — Kimi Code cannot read them. Safe to remove:

# Only if you previously installed via --kimi and are now on --kimi-code:
rm -rf ~/.config/agents/agents/msd-*.yaml ~/.agents/agents/msd-*.yaml 2>/dev/null || true

3. Reclaim MSD hooks a pre-1.10.0 install left in ~/.kimi

Before 1.10.0 (#2755), a --kimi-code install wrote its MSD [[hooks]] block, hook bundle and CommonJS marker into Kimi CLI's ~/.kimi/ instead of Kimi Code's own root. Upgrading fixes the destination but cannot clean up what the old bug already wrote, so those artifacts stay in ~/.kimi/ indefinitely — nothing reads them, and no uninstall path reaches them.

Reclaim them by adding --reclaim-kimi-legacy to the re-install:

npx @golem15/msd-core --kimi-code --global --reclaim-kimi-legacy

This removes MSD's managed [[hooks]] block from ~/.kimi/config.toml, plus MSD's own hook scripts, hooks/lib/ helpers and CommonJS marker under ~/.kimi/. Only exact MSD-owned filenames are touched: your own config.toml sections, your own scripts, and any package.json you wrote yourself are left alone, and directories are removed only when that cleanup leaves them empty.

Do not pass this flag if you also use Kimi CLI. MSD wraps its entries in the same # MSD Hooks BEGIN/END markers whichever product it installed for, and the command paths inside them are derived from the hooks root — so a block the old bug wrote for Kimi Code is byte-identical to the one a legitimate --kimi install writes. Nothing on disk can tell them apart, which is exactly why this cleanup is opt-in rather than automatic: on a machine with both products, the flag would remove Kimi CLI's working hooks. If you use both, leave ~/.kimi alone — the leftovers are inert for Kimi Code and harmless for Kimi CLI. To remove them later, uninstall Kimi CLI's install properly instead: npx @golem15/msd-core --kimi --global --uninstall.

The flag never acts silently. It is skipped, with a notice saying so, in each case where reclaiming would be wrong or impossible:

Situation	What happens
The install is not --kimi-code, or is --local	Warns that the flag was ignored — nothing in ~/.kimi is touched.
The same invocation also installs --kimi (including via --all)	Skipped: that run is creating a live Kimi CLI install in ~/.kimi, so the flag's premise does not hold.
KIMI_SHARE_DIR and KIMI_CODE_HOME name the same directory	Skipped: there is no separate legacy root, and reclaiming would delete the hooks this install just wrote. Aliases count — a symlink or a case variant on a case-insensitive filesystem is recognized as the same directory.
No MSD artifacts are found in ~/.kimi	Reports that there was nothing to reclaim.

4. Verify skills are discovered

After re-install, launch Kimi Code and confirm the MSD skills appear in the /skill: menu (or whatever surface Kimi Code uses for auto-discovered Agent Skills). Each msd-* skill should be present at ~/.kimi-code/skills/msd-*/SKILL.md.

5. Verify agent-skills query

msd-tools query agent-skills msd-planner

Should return the planner's prompt content (non-empty) — Phase 3's fallback reads the installed agent prompt on non-Claude runtimes.

What about workflows that dispatch named subagents?

Phase 4 (epic #2505) added runtime-aware dispatch. Workflows now resolve the subagent type via msd_run query resolve-dispatch-type --requested <role> --raw before dispatching. On Kimi Code, a role like msd-planner resolves to the plan built-in; the persona rides ${AGENT_SKILLS_PLANNER} (Phase 3's fallback) regardless of the resolved type. You do not need to edit any workflow files — the resolution is automatic.

What about the dormant guards?

Phase 0 (#2304 / PR #2518) made all seven Kimi-surface hooks read Kimi's payload shape, so their checks now run instead of exiting 0 on every call. Re-installing via --kimi-code --global picks up the fix automatically — the normalized guard scripts are part of the standard install.

What that does and does not buy you (#2547):

• Enforceable on Kimi — the PreToolUse blocks: the worktree cross-root write block (msd-worktree-path-guard) and the workflow force-add block (msd-workflow-guard). Kimi awaits PreToolUse results and honours a block.
• Not enforceable on Kimi — msd-read-injection-scanner's prompt-injection block. It is a PostToolUse hook, and kimi-cli's dispatch never inspects PostToolUse results, so the block cannot take effect there no matter what the hook emits. On Kimi, treat the read-injection scanner as advisory-only and rely on the prompt-level untrusted-input boundary instead.

Questions

• Can I keep both --kimi and --kimi-code installs? Yes — they install to separate config dirs (~/.kimi/ vs ~/.kimi-code/). Run both if you genuinely use both products.
• I only ever used Kimi Code — why is there anything in ~/.kimi at all? A MSD install older than 1.10.0 put it there (#2755). See step 3 above to reclaim it.
• Do I need to uninstall the old --kimi install first? No — --kimi-code --global writes to ~/.kimi-code/, which is separate. But if you no longer use Python kimi-cli, uninstalling the old install keeps things clean: npx @golem15/msd-core --kimi --global --uninstall.