Codex Migrate

Codex Migrate

A local-first, cross-platform tool for migrating, repairing, backing up, and exporting Codex sessions.

简体中文 · Installation · Safety · Contributing

[!IMPORTANT] Codex Migrate is an independent community project. It is not affiliated with, endorsed by, or sponsored by OpenAI. “Codex” and other OpenAI marks belong to OpenAI.

Codex Migrate works directly with a copied .codex/ directory or a legacy minimal Codex/ backup. New backups are complete copies stored in a visible Codex_backup/ folder. The importer uses rollout JSONL files as the source of truth and can merge selected sessions into an existing local Codex environment.

Screenshots

</td>
<td width="32%">
  
</td>

Features

• Migrate active and archived sessions across macOS, Windows, Linux, and WSL.
• Select individual projects and sessions before importing.
• Map old project paths to folders on the new device.
• Apply parent-directory mappings to many projects at once.
• Repair project paths in an existing .codex directory.
• Detect identical, prefix-compatible, and divergent session UUIDs.
• Create rollback snapshots before writes and delete old snapshots from the GUI.
• Export selected conversations as self-contained HTML, including embedded user images and tool screenshots.
• Use a native GUI in Chinese or English, following the system language by default.
• Use the same migration engine from the command line.

Backup contents

The backup exporter copies every file and directory under the selected Codex home into:

selected-folder/
└── Codex_backup/

This includes sessions, archived sessions, SQLite databases, Skills, configuration, plugins, logs, caches, rollback records, and other contents present in the source directory. Root-level login credential files such as auth.json are intentionally excluded.

[!WARNING] Although login credential files are excluded, a complete backup still contains private conversations, commands, output, images, local paths, configuration, and logs. Keep it private and protected. Quit Codex before exporting so database and WAL files are copied consistently.

Installation

Download a build for your platform from the repository’s Releases page.

• Windows: extract the ZIP and run Codex Migrate.exe.
• macOS: extract the ZIP and move Codex Migrate.app to Applications. On first launch, Control-click the app and choose Open. If macOS still blocks it, use System Settings → Privacy & Security → Open Anyway.
• Linux: extract the archive and run codex-migrate-gui.

Release builds are not currently signed with commercial certificates or notarized by Apple. Windows SmartScreen or macOS Gatekeeper may show a warning. Always verify the release checksum before running a downloaded binary.

Build from source

Requirements:

• Rust stable toolchain
• Platform build tools supported by eframe

git clone https://github.com/ChenglongLi777/codex-migrate.git
cd codex-migrate
cargo test --all-targets --features gui
cargo build --release --features gui --bins

macOS application bundle:

./scripts/package-macos.sh

Generated executables:

target/release/codex-migrate
target/release/codex-migrate-gui

Typical GUI workflow