codex-rehome supports moving Codex Desktop workspaces across Mac and Windows computers.
| Direction | Status | Source script | Target restore |
|---|---|---|---|
| Mac to Windows | Supported | create_mac_codex_migration_package.sh |
Restore-Codex-To-Windows.ps1 |
| Windows to Mac | Supported | create_windows_codex_migration_package.ps1 |
Restore-Codex-To-Mac.sh |
| Windows to Windows | Supported | create_windows_codex_migration_package.ps1 |
Restore-Codex-To-Windows.ps1 |
| Mac to Mac | Supported | create_mac_codex_migration_package.sh |
Restore-Codex-To-Mac.sh |
The standard workflow is designed to migrate:
Standard mode excludes sensitive or machine-specific files by default:
auth.json.env and .env.*.gitnode_modulesThe target computer should log in again manually when Codex, GitHub, browser integrations, Feishu, Gmail, or other external services request it.
Restore scripts use merge restore by default. They add packaged sessions, archived sessions, skills, plugin cache, generated images, and session_index.jsonl entries while preserving target login/config identity files. Full ~/.codex replacement requires --replace-codex-home on Mac or -ReplaceCodexHome on Windows. State database replacement requires --replace-state or -ReplaceState.
After restoring, run the verifier for the target OS:
.\Verify-Codex-Windows-Restore.ps1
or:
bash ./Verify-Codex-Mac-Restore.sh --json
Then open Codex and check recent threads and migrated project folders from their new target paths.
For restores with selected_chats/, verifier readiness requires selected chat IDs to exist in restored .codex/sessions, .codex/session_index.jsonl, and target state_*.sqlite.threads. It also checks that rollout paths exist, thread cwd values point to restored target project paths, selected JSONL metadata has been path-mapped, old source paths are gone from selected JSONL files, and restored projects are present in .codex-global-state.json.
The validation model has four layers: file layer, path mapping layer, index layer, and app registration layer. File/path/index readiness can make internal thread reads work, but it is not enough to make the Codex Desktop project sidebar show the restored workspace.
Data-layer readiness is not the same as live desktop frontend readiness. Project folders must be registered through Codex Desktop’s own open-workspace path, normally codex app <restored-project-path>. Hand-editing .codex-global-state.json alone can be overwritten by the running desktop app. Current schema v3 restore invokes /Applications/Codex.app/Contents/Resources/codex app <restored-project-path> on Mac and attempts codex app <restored-project-path> on Windows after project restore, then records the result in codex-rehome-project-registration-report.json. If Windows packaged-app permissions block CLI execution, manually reopen the restored project folder from Codex Desktop and rerun the verifier.
Intel Mac and Apple Silicon should not affect the core Codex data migration because architecture-specific dependency folders and binary-heavy runtime paths are excluded by default. Reinstall or rebuild project dependencies such as node_modules, virtual environments, compiled artifacts, or native tools on the target machine.
Project folders are packaged under projects/. Mac restores can copy them automatically with Restore-Codex-To-Mac.sh --restore-projects, which defaults to ~/Documents/Codex-Restored-Projects; pass --projects-dir <dir> to choose another location. Windows restores can copy them with Restore-Codex-To-Windows.ps1 -RestoreProjects, which defaults to %USERPROFILE%\Documents\Codex-Restored-Projects; pass -ProjectsDir <dir> to choose another location.
Mac and Windows packages are generated with schema version 3 metadata exports for thread rows/path mapping/project UI registry, LF/no-BOM SHA256SUMS.txt, and both text and JSON manifests. Windows-generated zips use forward-slash entries so macOS can unzip them directly. Mac and Windows target verification check selected chats when present, session_index.jsonl readiness, SQLite thread readiness, path mapping readiness, restored project folders, global project registry readiness, app project registration readiness, and forbidden-file counts where available.