How to Migrate from Legacy Kimi-Code Configurations: Complete Guide

To migrate from legacy kimi-code configurations, run the kimi migrate CLI command or use the @moonshot-ai/migration-legacy package to transfer configs, MCP servers, and chat history from ~/.kimi/ to ~/.kimi-code/ without deleting your original data.

The transition from legacy kimi-cli (Python/uv-based) to modern kimi-code (Node.js with native binary) requires moving your existing setup to a new architecture. The MoonshotAI/kimi-code repository provides a dedicated migration package that handles this process automatically while preserving data integrity.

Understanding the Architecture Differences

Legacy installations stored data under ~/.kimi/ and relied on Python environments. Modern kimi-code uses a native Node.js binary with a rewritten terminal interface and stores data under ~/.kimi-code/. The migration tool bridges these environments by translating legacy formats to the new schema.

Automatic Detection on First Launch

When you launch the kimi binary for the first time after installation, it automatically checks for a legacy home directory. If detected, the CLI presents three options:

1. Migrate now – Executes the migration immediately
2. Migrate later – Postpones the operation to a future session
3. Never ask again – Disables future migration prompts

This detection logic is implemented in [packages/migration-legacy/src/detect.ts](https://github.com/MoonshotAI/kimi-code/blob/main/packages/migration-legacy/src/detect.ts), which discovers existing ~/.kimi/ directories and collects initial metadata.

Running the Migration Manually

You can initiate migration at any time using the CLI:

kimi migrate

This command invokes the runMigration function from [packages/migration-legacy/src/run-migration.ts](https://github.com/MoonshotAI/kimi-code/blob/main/packages/migration-legacy/src/run-migration.ts), which orchestrates the entire process and generates a comprehensive MigrationReport.

What Gets Migrated

The migration process handles five core components:

Configuration Files

The tool parses config.toml and rewrites it to the new schema. If conflicts occur, it creates a sibling file named config.migrated-from-kimi-cli.toml to preserve manual resolution options. This logic resides in [packages/migration-legacy/src/steps/config.ts](https://github.com/MoonshotAI/kimi-code/blob/main/packages/migration-legacy/src/steps/config.ts).

MCP Server Definitions

Legacy MCP server entries—including those using optional SSE transport—are merged into the new mcp.toml format. Conflicting entries are maintained in a separate sibling file for review. See [packages/migration-legacy/src/steps/mcp.ts](https://github.com/MoonshotAI/kimi-code/blob/main/packages/migration-legacy/src/steps/mcp.ts) for implementation details.

User History and Skills

Raw input history files are copied to the new home directory while preserving ordering, as implemented in [packages/migration-legacy/src/steps/user-history.ts](https://github.com/MoonshotAI/kimi-code/blob/main/packages/migration-legacy/src/steps/user-history.ts). Locally defined skill definitions are migrated via [packages/migration-legacy/src/steps/skills.ts](https://github.com/MoonshotAI/kimi-code/blob/main/packages/migration-legacy/src/steps/skills.ts).

Chat Sessions

Each session bucket is processed to translate the legacy wire format into the new transcript format. The migration walks session directories in [packages/migration-legacy/src/sessions/index.ts](https://github.com/MoonshotAI/kimi-code/blob/main/packages/migration-legacy/src/sessions/index.ts), with individual session conversion handled by [packages/migration-legacy/src/sessions/migrate-one.ts](https://github.com/MoonshotAI/kimi-code/blob/main/packages/migration-legacy/src/sessions/migrate-one.ts).

Migration Safety and Idempotency

The migration is idempotent: sessions already processed are detected via a marker file and skipped on subsequent runs. The process never deletes or overwrites original legacy data—it only reads from ~/.kimi/ and writes to ~/.kimi-code/. After migration, imported sessions appear tagged with [imported] in the session picker for easy identification.

What Is Not Migrated

Two categories require manual intervention:

• OAuth credentials and MCP authorizations – You must run kimi login again and re-authorize MCP servers
• Legacy plugins – These are out of scope and must be re-installed manually

Programmatic Migration API

For custom tooling or CI/CD pipelines, import the migration package directly:

import { runMigration } from '@moonshot-ai/migration-legacy';
import { detectLegacyHome } from '@moonshot-ai/migration-legacy/src/detect.js';

async function performMigration() {
  const legacyHome = await detectLegacyHome();
  const newHome = `${process.env.HOME}/.kimi-code`;

  const plan = {
    detectedMcpOauthServers: [],
    oauthCredentials: [],
    detectedPlugins: [],
  };

  const report = await runMigration({
    plan,
    scope: {
      config: true,
      mcp: true,
      userHistory: true,
      skills: true,
      sessions: true,
    },
    source: legacyHome,
    target: newHome,
    onProgress: msg => console.log(msg),
    onSessionProgress: (done, total) => 
      console.log(`Sessions: ${done}/${total}`),
  });

  console.log('Migration finished:', report);
}

Inspecting Migration Results

After completion, examine the generated report:

import { readReport } from '@moonshot-ai/migration-legacy/src/report.js';

async function showReport() {
  const report = await readReport(`${process.env.HOME}/.kimi-code`);
  console.dir(report, { depth: null });
}

The MigrationReport includes timestamps, migrated component lists, and conflict notices. Results are written to the target home via writeReport and appended to writeMigrationErrorsLog for cross-run troubleshooting, as implemented in [packages/migration-legacy/src/report.ts](https://github.com/MoonshotAI/kimi-code/blob/main/packages/migration-legacy/src/report.ts). The marker file logic in [packages/migration-legacy/src/marker.ts](https://github.com/MoonshotAI/kimi-code/blob/main/packages/migration-legacy/src/marker.ts) ensures idempotency across runs.

Summary

• Legacy data lives in ~/.kimi/; modern data lives in ~/.kimi-code/
• Run kimi migrate to start migration, or let the CLI prompt you on first launch
• The process migrates configs, MCP servers, user history, skills, and sessions
• Migration is idempotent and non-destructive—original data remains untouched
• OAuth and plugins are not migrated and require manual setup
• Use the programmatic API from @moonshot-ai/migration-legacy for custom automation

Frequently Asked Questions

Does the migration delete my old kimi-cli data?

No. The migration tool only reads from ~/.kimi/ and writes to ~/.kimi-code/. Your original configuration, sessions, and history remain intact in the legacy directory. The process is designed to be completely non-destructive.

Can I run the migration multiple times safely?

Yes. The migration is idempotent. Already-migrated sessions are detected via a marker file (migration-errors.log) and skipped automatically. You can re-run kimi migrate without duplicating data or corrupting existing sessions.

Why didn't my OAuth credentials transfer to the new installation?

OAuth login credentials and MCP service authorizations are intentionally excluded from migration for security reasons. You must run kimi login again after migration and re-authorize any MCP servers manually. This ensures fresh tokens and proper security boundaries.

How do I know which sessions were imported from the legacy version?

After migration, sessions that originated from kimi-cli are tagged with [imported] in the session picker interface. This visual marker makes it easy to distinguish legacy conversations from new ones created in kimi-code.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}