Codex project chat migration

Codex Project Chat Migration

Overview

Use this skill to recover local Codex project chats hidden by provider/auth metadata changes. Treat the operation as metadata reassignment, not chat copying: the same local chats are made visible to the target provider identity.

Workflow

1. Identify the active provider from ~/.codex/config.toml or ask for an explicit target when the user is switching back to a prior provider.
2. Run a dry run first:

python3 ~/.codex/skills/codex-project-chat-migration/scripts/migrate_project_chats.py

3. Review the reported database provider counts, rollout JSONL provider counts, mismatches, affected threads, missing rollout files, blocking provider migration guards, and proposed target provider.
4. Apply only after the dry run looks correct:

python3 ~/.codex/skills/codex-project-chat-migration/scripts/migrate_project_chats.py --apply

5. Restart Codex after applying so the app reloads local thread state. Do not force quit the app from the skill unless the user explicitly asks.

Script Usage

Use scripts/migrate_project_chats.py for deterministic diagnosis and migration.

Common options:

• --codex-home PATH: override Codex home; defaults to $CODEX_HOME or ~/.codex.
• --target-provider PROVIDER: override the provider to migrate chats to; otherwise the script reads model_provider from config.toml.
• --source-provider PROVIDER: repeat to migrate only specific source providers; when omitted, all non-target providers and missing rollout providers are candidates.
• --active-only: exclude archived threads.
• --state-db PATH: use a specific Codex state SQLite file; otherwise the script prefers state_5.sqlite and falls back to the highest state_*.sqlite.
• --apply: create backups and write changes. Without this flag the script never mutates files.

The dry run may report Blocking provider migration guards when old SQLite triggers would force the target provider back to a previous provider. This usually means a previous provider migration left a guard table such as <provider>_provider_migration_ids. On --apply, the script clears the affected thread IDs from those guard tables before updating threads.model_provider.

Examples:

python3 ~/.codex/skills/codex-project-chat-migration/scripts/migrate_project_chats.py --target-provider cctq
python3 ~/.codex/skills/codex-project-chat-migration/scripts/migrate_project_chats.py --target-provider openai --source-provider cctq --apply

Safety Rules

• Never print or inspect API keys, session tokens, or auth.json contents.
• Always run dry-run before --apply.
• Always keep SQLite and rollout JSONL session_meta.payload.model_provider in sync. Updating only SQLite can make chats appear at launch and disappear after the app reconciles rollout metadata.
• Treat Blocking provider migration guards as a first-class safety signal. If present, confirm the guard's forced provider matches the intended source provider before applying.
• Backups are required before mutation. The script writes them under ~/.codex/backups/.
• Use an explicit --target-provider when reversing a migration or when the active provider in config.toml is not the provider the user wants.
• If the user asks whether switching back will lose data, explain that this changes local ownership metadata; backups preserve rollback points, and the original chat files are not deleted by this migration.

Verification

After applying, run the script again without --apply. A healthy result shows no affected threads, no database/rollout provider mismatch for the migrated set, and no blocking provider migration guards. If the UI still omits chats, restart Codex and re-run the dry run before making additional changes.