A pragmatic backup and restore workflow for moving Codex Desktop local state, threads, plugins, and skills between Macs.
Am 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. You need to set it up as new. So here we go...
I didn't want too much ceremony moving my, err, precious, Codex Desktop setup from one Mac to another and wanted to preserve my active threads, local state, installed skills, plugins, and working context. Don't judge me on AI use, 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 moving Codex local state between Macs.
What Gets Moved
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 data
Treat the backup as sensitive because it can include auth tokens and local conversation history.
Back Up The Old Mac
Quit Codex first, then run this from Terminal on the old 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.
Restore On The New Mac
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.
Do Not Forget The Workspace
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!
Sanity Check
After reopening Codex:
- Confirm the thread appears in the sidebar.
- Open it and check that recent messages are present.
- Confirm the workspace path exists.
- Reconnect any cloud connectors if prompted. Some connectors may show as installed but still require re-authentication. That is normal when moving machines.
Cleanup
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.
The Practical Summary
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.