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

> Easily migrate legacy Kimi-code configurations to the new format using the CLI command or migration package. Transfer configs, servers, and chat history safely without data loss.

- Repository: [Moonshot AI/kimi-code](https://github.com/MoonshotAI/kimi-code)
- Tags: migration-guide
- Published: 2026-07-25

---

**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)](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:

```bash
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)](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`](https://github.com/MoonshotAI/kimi-code/blob/main/config.toml) and rewrites it to the new schema. If conflicts occur, it creates a sibling file named [`config.migrated-from-kimi-cli.toml`](https://github.com/MoonshotAI/kimi-code/blob/main/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)](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`](https://github.com/MoonshotAI/kimi-code/blob/main/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)](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)](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)](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)](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)](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:

```typescript
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:

```typescript
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)](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)](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.