As an Open AI Partner and I'm in the middle of switching Macs from M1 Air to M4 Air. What. a. pain. Especially in the enterprise world where you cannot just simply migrate everything from one Mac to another like you can do personally. You need to set it up as new. So here we go...
I didn't want too much ceremony moving my, err, precious, OpenAI Codex Desktop setup from one Mac to another and wanted to preserve my active Codex app threads, local state, installed skills, plugins, and working context. Hey, don't judge me on choice of LLMs, I do use Kiro too tho'!
Politics aside, the short version: most of what you need lives under ~/.codex
.
This is not a polished migration tool. It is a pragmatic backup-and-restore approach that worked for me moving Codex local state between Macs.
(oh, the AI didn't work, but you get the gist 🤣)
The important Codex state is in:
~/.codex
The useful parts include:
~/.codex/sessions/
-
conversation rollout files
~/.codex/session_index.jsonl -
thread index
~/.codex/state_*.sqlite -
thread metadata and local state
~/.codex/logs_*.sqlite -
local runtime logs
~/.codex/config.toml -
Codex configuration
~/.codex/plugins/
, ~/.codex/skills/
, ~/.codex/cache/
-
installed plugins, skills, and cached assets
~/.codex/auth.json -
authentication dataTreat the backup as sensitive because it can include auth tokens and local conversation history.
Quit Codex first, then run this from Terminal on the old, ok, retiring, Mac:
`$ COPYFILE_DISABLE=1 tar --no-xattrs \`
--exclude='.codex/vendor_imports/skills/.git/fsmonitor--daemon.ipc' \
-czf ~/Desktop/codex-backup.tgz \
-C ~ .codex
If your version of `tar`
does not support `--no-xattrs`
, use this:
$ COPYFILE_DISABLE=1 tar \
--exclude='.codex/vendor_imports/skills/.git/fsmonitor--daemon.ipc' \
-czf ~/Desktop/codex-backup.tgz \
-C ~ .codex
The exclude matters because git can leave a filesystem socket at:
$ ~/.codex/vendor_imports/skills/.git/fsmonitor--daemon.ipc
tar
cannot archive sockets, and you do not need that file on the new machine.
The COPYFILE_DISABLE=1
and --no-xattrs
flags avoid macOS extended attribute noise. Those attributes are not important for restoring the Codex thread content.
Move codex-backup.tgz
to the new Mac's Desktop.
Quit Codex on the new Mac, then run:
$ cd ~
`$ mv ~/.codex ~/.codex.backup.$(date +%Y%m%d-%H%M%S) 2>/dev/null`
`$ COPYFILE_DISABLE=1 tar -xzf ~/Desktop/codex-backup.tgz -C ~`
Then reopen Codex.
Your threads should reappear, including their local metadata and session files.
Codex thread history and project files are separate.
Moving ~/.codex
restores the Codex-side state, but it does not move your actual project folders. If a thread points to a workspace path, make sure that folder also exists on the new Mac.
For example:
$ mkdir -p ~/Documents/"Client Pursuit"
If your work lives in OneDrive, let OneDrive fully sync the relevant folders before expecting every file reference to work:
$ ~/Library/CloudStorage/OneDrive-Slalom/Documents/"Client Pursuit"
-- which might be one of your many (manyⁿ) folders! After reopening Codex:
After confirming the transfer worked, delete the archive from both machines:
$ rm ~/Desktop/codex-backup.tgz
The archive contains local Codex state and may include credentials, so do not leave it sitting around.
Back up ~/.codex
, exclude the Git fsmonitor socket, restore it on the new machine, then make sure the referenced project folders are present.
That is enough to carry active Codex threads and local context across Macs.