The Migration System

Every time you launch Claude Code it may silently fix stale settings, remap deprecated model aliases, move fields between files, or re-surface UI dialogs — all before you see the first prompt. This is the migration system: a small but precisely designed set of one-shot functions that run inside runMigrations() in main.tsx.

Migrations in Claude Code are not database schema migrations. There is no migration table, no rollback, and no runner framework. Instead, every migration function is idempotent by design — it detects its own pre/post conditions and exits immediately if the work is already done. The entire set runs at every startup, protected by a single version number that short-circuits the whole block once all migrations have been applied.

All synchronous migrations are wrapped in a single function defined in main.tsx. It is called during the Commander preAction hook — after config is loaded, before the REPL starts.

// main.tsx — line 323
// @[MODEL LAUNCH]: Consider any migrations you may need for model strings.
// See migrateSonnet1mToSonnet45.ts for an example.

// Bump this when adding a new sync migration so existing users re-run the set.
const CURRENT_MIGRATION_VERSION = 11;

function runMigrations(): void {
  if (getGlobalConfig().migrationVersion !== CURRENT_MIGRATION_VERSION) {
    migrateAutoUpdatesToSettings();
    migrateBypassPermissionsAcceptedToSettings();
    migrateEnableAllProjectMcpServersToSettings();
    resetProToOpusDefault();
    migrateSonnet1mToSonnet45();
    migrateLegacyOpusToCurrent();
    migrateSonnet45ToSonnet46();
    migrateOpusToOpus1m();
    migrateReplBridgeEnabledToRemoteControlAtStartup();
    if (feature('TRANSCRIPT_CLASSIFIER')) {
      resetAutoModeOptInForDefaultOffer();
    }
    if ("external" === 'ant') {   // internal Anthropic builds only
      migrateFennecToOpus();
    }
    // Stamp the version so we skip next time
    saveGlobalConfig(prev => prev.migrationVersion === CURRENT_MIGRATION_VERSION
      ? prev
      : { ...prev, migrationVersion: CURRENT_MIGRATION_VERSION });
  }

  // Async migration — fire-and-forget, non-blocking
  migrateChangelogFromConfig().catch(() => {});
}

Three design decisions stand out here:

1. Version gate: migrationVersion is stored in ~/.claude.json. Once it equals CURRENT_MIGRATION_VERSION, the entire sync block is skipped — avoiding 11 redundant saveGlobalConfig lock+re-read cycles on every startup.
2. Version bump rule: The comment explicitly says — bump the constant whenever you add a new sync migration so existing users re-run the full set.
3. Async separation: migrateChangelogFromConfig is async and involves file I/O, so it runs fire-and-forget after the sync block.

There are currently 11 sync migration functions plus one async one. Here is every file with what it does, the idempotency mechanism, and which config storage it touches.

Every migration must be safe to call multiple times. Two patterns emerge across the codebase:

Pattern A — Completion flag in GlobalConfig

Used when a migration needs to run exactly once but the "already done" state is not self-evident from the data (e.g. resetProToOpusDefault, migrateSonnet1mToSonnet45). A boolean or timestamp is written to ~/.claude.json and checked at the top of the function.

// migrateSonnet1mToSonnet45.ts — completion flag pattern
export function migrateSonnet1mToSonnet45(): void {
  const config = getGlobalConfig()
  if (config.sonnet1m45MigrationComplete) {
    return  // already done — exit immediately
  }

  const model = getSettingsForSource('userSettings')?.model
  if (model === 'sonnet[1m]') {
    updateSettingsForSource('userSettings', {
      model: 'sonnet-4-5-20250929[1m]',
    })
  }

  saveGlobalConfig(current => ({
    ...current,
    sonnet1m45MigrationComplete: true,
  }))
}

Pattern B — Self-idempotent (data speaks for itself)

Used when the migration condition is a direct check on the current value — if the data has already been migrated, the check simply returns false and nothing is written (e.g. all model alias migrations). Reading and writing the same settings source (userSettings) is key to this pattern — the comment in migrateLegacyOpusToCurrent.ts explains: "Reading and writing the same source keeps this idempotent without a completion flag, and avoids silently promoting 'opus' to the global default for users who only pinned it in one project."

// migrateLegacyOpusToCurrent.ts — self-idempotent pattern
export function migrateLegacyOpusToCurrent(): void {
  if (getAPIProvider() !== 'firstParty') return
  if (!isLegacyModelRemapEnabled()) return

  const model = getSettingsForSource('userSettings')?.model
  if (
    model !== 'claude-opus-4-20250514' &&
    model !== 'claude-opus-4-1-20250805' &&
    model !== 'claude-opus-4-0' &&
    model !== 'claude-opus-4-1'
  ) {
    return  // data already clean — nothing to do
  }

  updateSettingsForSource('userSettings', { model: 'opus' })
  saveGlobalConfig(current => ({
    ...current,
    legacyOpusMigrationTimestamp: Date.now(),
  }))
  logEvent('tengu_legacy_opus_migration', { from_model: model })
}

Claude Code has multiple settings sources that are merged in priority order: userSettings → projectSettings → localSettings → policySettings. Migrations are deliberately scoped to only touch userSettings (and occasionally localSettings). The comment in nearly every model migration file repeats the same rationale:

This constraint prevents a subtle class of bugs: if a migration read from merged settings, it might see a project-scoped setting and "helpfully" write that value into the global userSettings, suddenly making a per-project preference the new default everywhere.

Alongside the startup migration functions, config.ts contains a lower-level migrateConfigFields() that runs every time the config file is read from disk. This handles the oldest schema changes — before the current versioned migration system existed.

// config.ts — runs on every config read
function migrateConfigFields(config: GlobalConfig): GlobalConfig {
  if (config.installMethod !== undefined) {
    return config  // already migrated
  }

  // autoUpdaterStatus is removed from the type but may exist in old configs
  const legacy = config as GlobalConfig & {
    autoUpdaterStatus?: 'migrated' | 'installed' | 'disabled' | 'enabled' | ...
  }

  switch (legacy.autoUpdaterStatus) {
    case 'migrated':  installMethod = 'local';   break
    case 'installed': installMethod = 'native';  break
    case 'disabled':  autoUpdates  = false;      break
    ...
  }

  return { ...config, installMethod, autoUpdates }
}

There is also a removeProjectHistory() function that strips the old inline history field from project configs on every read — this field was migrated to separate history.jsonl files, but old configs still carry the field.

Migrations are observable. Most functions call logEvent() to record what happened to Anthropic's telemetry pipeline. This lets the team know when a migration is still being applied to users in the wild vs. when it is safe to remove the migration code.

Notably, migrateSonnet1mToSonnet45 and migrateReplBridgeEnabledToRemoteControlAtStartup do not emit analytics events — they are considered lower-risk housekeeping.

The source code even contains a comment pointing future engineers in the right direction:

The recipe from the existing codebase:

1. Create src/migrations/myNewMigration.ts with a single exported function.
2. Choose an idempotency strategy: completion flag in GlobalConfig, or self-idempotent data check.
3. Only read from and write to userSettings (or localSettings for project-scoped data). Never read merged settings.
4. Call logEvent('tengu_my_migration_name', {...}) with relevant metadata.
5. Wrap the body in try/catch and call logError in the catch — migrations must never throw and break startup.
6. Import the function in main.tsx and add it inside the if (migrationVersion !== CURRENT_MIGRATION_VERSION) block.
7. Bump CURRENT_MIGRATION_VERSION so existing users re-run the updated set.

// Template: src/migrations/myNewMigration.ts
import { logEvent } from '../services/analytics/index.js'
import { logError } from '../utils/log.js'
import {
  getSettingsForSource,
  updateSettingsForSource,
} from '../utils/settings/settings.js'

export function myNewMigration(): void {
  // self-idempotent guard: check if work is already done
  const model = getSettingsForSource('userSettings')?.model
  if (model !== 'old-alias') return

  try {
    updateSettingsForSource('userSettings', { model: 'new-alias' })
    logEvent('tengu_my_new_migration', {})
  } catch (error) {
    logError(new Error(`Failed to run myNewMigration: ${error}`))
  }
}