Mac-to-Mac migration guide · 日本語版
Transfer Codex
to a new Mac.
Moving Codex to a different Mac means copying more than a GitHub repository. Keep the local conversation you want to resume, the branch you have not pushed, and the custom skill your project depends on.
Codex Migrate is an independent, open-source tool for moving local Codex workspaces between Macs over SSH. The free CLI is in beta. Prefer a packaged app and personal, best-effort support? Get the signed $49 Mac beta for Apple silicon Macs. Review the beta limitations before buying, and keep your old Mac and an independent backup.
Why signing in on the new Mac is not enough
Your OpenAI account handles access to Codex, but some of the environment you use while working is stored locally on your Mac. Signing into the same account on another Mac may not reproduce local conversations, custom configuration, skills, worktrees, unpushed branches, stashes, or files that never reached a remote.
If Codex history appears missing after changing Macs, do not erase or repurpose the old Mac yet. First identify which work exists only there. Follow the missing Codex history checklist before copying anything.
Choose the right way to move
- Git clone or pull: best when everything important is committed and pushed. It does not recover unpushed branches, untracked files, local Codex conversations, or machine-specific configuration.
- Apple Migration Assistant: appropriate for moving a broad Mac user account when it completes successfully. It is broader than a Codex-only transfer and may not suit a selectively configured new Mac.
- Manual copy or rsync: workable for experts who already know the exact paths, exclusions, ownership, linked-worktree dependencies, backup plan, and verification procedure.
- Codex Migrate: focused on inspecting, staging, backing up, transferring, and verifying local Codex work while preserving the new Mac’s authentication and installation identity.
Select the work, not just the repository
Using Codex in the ChatGPT desktop app? This guide covers local OpenAI Codex conversations and workspace files, not ordinary ChatGPT cloud chats, account-to-account history transfers, or all ChatGPT modes. The same local-data distinction matters if you still call it the Codex app. Compatibility varies by version; review the migration plan before changing destination files.
The migration includes active and archived local conversations, configuration, project organization, skills, rules, memories, automations, and relevant Codex state. You explicitly select the workspace folders to copy.
Inside those selected roots, the copy includes Git history, local branches, tags, stashes, linked-worktree metadata, and uncommitted or untracked files. Repositories or worktree directories outside those roots are not automatically included. Inspect the plan and include every location you still need.
Keep the new Mac’s login
Install Codex and sign in on the new Mac first. Codex Migrate preserves that machine’s authentication and installation identity. It does not copy the old Mac’s Codex login or SSH private-key directory. Credentials embedded in selected workspace files are still part of those files—review your selections carefully.
Transfer, pause, resume
Enable Remote Login for the destination user, verify the SSH host fingerprint, and inspect both Macs before enabling changes. Staging is resumable: after an interruption, rerun with the same destination and scope to reuse completed data. Wi-Fi, Ethernet, and working Thunderbolt networking can all carry SSH; plugging in a USB-C cable alone does not establish a network connection. After verifying the configured Mac, inspection checks its reachable private network addresses and selects the fastest verified route.
Verify before you retire the old Mac
Final installation requires Codex closed on both Macs and a verified destination backup. If the usernames differ, old absolute paths may need a reviewed compatibility alias. Open important conversations, check custom skills, and inspect your repositories on the new machine. Do not erase the old Mac just because a progress bar reached 100%.
New-Mac migration checklist
- Keep the old Mac unchanged and maintain an independent backup.
- Install Codex on the new Mac, open it, and sign in once.
- Enable Remote Login only for the destination account you intend to use.
- Connect the Macs over Wi-Fi, Ethernet, or a working USB-C/Thunderbolt network route.
- Inspect the proposed Codex data and workspace folders before enabling changes.
- Stage the transfer, then allow finalization only after the destination backup verifies.
- Open important conversations and inspect Git status, branches, worktrees, skills, and unfinished files on the new Mac.
- Retain the old Mac until you have worked successfully from the new one.
Common questions
Can I just copy the .codex folder?
A blanket copy can also replace machine-specific authentication or installation identity, and it still does not include project folders stored elsewhere. Codex Migrate deliberately preserves the new Mac’s authentication and excludes disposable runtime state.
Does this copy repositories too?
Yes, when you explicitly select their workspace roots. Selected folders include complete Git directories, branches, worktrees, stashes, uncommitted changes, and untracked files. Dependencies outside the selection are reported rather than silently omitted.
Does a USB-C or Thunderbolt cable make it faster?
It can, but only when the cable and Mac configuration provide a working network connection. A charging-only or limited USB-C cable may be slower than Thunderbolt or may not create a usable route at all. The transfer still runs over SSH.
The source Mac is left intact. Backups and verification reduce risk; they do not replace an independent backup or guarantee compatibility with every Codex version.