Encrypted cross-device sync for OpenAI Codex local state. Start a conversation on one Mac, continue it on another; keep your config, rules, skills and memories in step.
- Your storage, your key. Files are gzip-compressed and age-encrypted before they leave the machine. The bucket (Cloudflare R2, S3, GCS, any S3-compatible service, or WebDAV) only ever sees ciphertext.
- Merge, don't clobber. Thread names and prompt history are unioned across machines; a file changed on both sides becomes a conflict you resolve, never a silent overwrite.
- Careful by default. First pull offers a backup, removals go to a trash directory, an empty bucket can never wipe your local files.
codex-sync is a fork of claude-sync (MIT) with the sync engine kept and everything Codex-specific rebuilt — see NOTICE. It is early software (v0.x): macOS, built from source, tested by its author on two Macs. Issues and pull requests are welcome.
- How it works
- Install
- Set up
- Everyday use
- What gets synced
- How sync behaves
- Seeing pulled threads in the desktop app
- Troubleshooting
- Security
- Limitations
- Contributing
- License
Codex keeps everything that matters in plain files under ~/.codex (or
$CODEX_HOME): one JSONL "rollout" file per conversation, an index of thread
names, your prompt history, config.toml, rules, skills and memories. Its
SQLite databases are derived from those files and are rebuilt on startup.
codex-sync treats the files as the source of truth:
pushencrypts every file that changed since the last sync and uploads it to your bucket; files you deleted locally are reported and kept in storage until you runpush --force.pulldownloads what changed remotely, merges the two shared index files, saves both-sides-changed files as conflict sidecars, and moves files that vanished from the remote to a trash directory.- A small state file (
~/.codex-sync/state.json) remembers each file's hash so both commands only touch what changed.
Two things to know up front:
- Keep every machine on the same Codex version. An older engine silently hides threads written by a newer one.
- The ChatGPT desktop app does not notice pulled threads on its own. Run
codex-sync pull --desktop(with the app quit) — see below.
Requirements: macOS, and a bucket at one of the supported providers (next section). Building from source additionally needs Go 1.24 or newer.
Download the asset for your platform from the
latest release, check it
against the checksums.txt published beside it, and put it on your PATH:
shasum -a 256 --ignore-missing -c checksums.txt
chmod +x codex-sync-darwin-arm64
mv codex-sync-darwin-arm64 ~/.local/bin/codex-sync
xattr -d com.apple.quarantine ~/.local/bin/codex-sync # clears the download quarantine
codex-sync --versionOr build from source:
git clone https://github.com/d-jiao/codex-sync
cd codex-sync
make build && make install # installs ~/.local/bin/codex-sync (override with INSTALL_DIR=...)
codex-sync --versionMake sure ~/.local/bin is on your PATH. Once installed, codex-sync update
upgrades in place from the latest release and refuses any download whose
checksum does not match.
| Provider | Free tier | Best for |
|---|---|---|
| Cloudflare R2 (recommended) | 10 GB storage, 1M writes, 10M reads/month, no egress fees | personal use |
| AWS S3 | 5 GB for 12 months, then ~$0.023/GB | AWS users |
| Google Cloud Storage | 5 GB, 5K writes, 50K reads/month | GCP users |
| S3-compatible | varies | Backblaze B2, MinIO, Wasabi, DigitalOcean Spaces, self-hosted |
| WebDAV | your own server | Nextcloud / ownCloud users |
Storage needs scale with your conversation history: sessions/ and
archived_sessions/ range from a few MB to a few hundred MB on a long-lived
install, which fits in every free tier above.
Cloudflare R2
- Cloudflare Dashboard → R2 Object Storage → Create bucket (e.g.
codex-sync) - Manage R2 API Tokens → Create API Token with Object Read & Write permission
You'll need: Account ID, Access Key ID, Secret Access Key.
AWS S3
- S3 Console → Create bucket
- IAM Security Credentials → Create access keys
You'll need: Access Key ID, Secret Access Key, Region.
Google Cloud Storage
- Cloud Storage → Create bucket
- Service Accounts → Create service account with the Storage Object Admin role → Create JSON key
You'll need: Project ID and the service-account JSON file (or run gcloud auth application-default login).
S3-compatible (Backblaze B2, MinIO, Wasabi, DigitalOcean Spaces, …)
Any provider with an S3-compatible API works through the S3-compatible (custom endpoint) option. Create a bucket and an application key with your provider, then pass its S3 endpoint URL:
codex-sync init --provider s3-compatible --endpoint https://s3.us-west-004.backblazeb2.comYou'll need: Endpoint URL, Access Key ID, Secret Access Key, Bucket. The signing
region is auto-detected from the endpoint (e.g. us-west-004); providers that
ignore it get auto.
For servers that don't resolve buckets as subdomains (Ceph RGW, MinIO without
wildcard DNS), add --use-path-style to address objects as
endpoint/bucket/key instead of bucket.endpoint/key:
codex-sync init --provider s3-compatible --endpoint https://ceph.example.com --use-path-styleIt is off by default and not needed for Backblaze B2, Wasabi or DigitalOcean Spaces. Custom endpoints also relax the AWS SDK's default integrity-checksum headers, which some providers reject; AWS S3 itself is unaffected.
WebDAV (Nextcloud, ownCloud, …)
No bucket to create — point at your existing server.
- Nextcloud: Settings → Security → Devices & sessions → Create app password
- Note your WebDAV URL:
https://your-server/remote.php/dav/files/USERNAME/
You'll need: WebDAV URL, Username, App password. The wizard creates a
codex-sync subdirectory for you.
Object names are percent-encoded per path segment, so attachments whose names
contain spaces, #, ? or % upload, list and download correctly.
codex-sync initThe wizard walks you through:
- Storage provider and its credentials (all of them can also be passed as
flags — see
codex-sync init --help). - Encryption key. Passphrase (recommended, at least 12 characters):
the same passphrase produces the same key on every machine, so there is
nothing to copy around. Random key: no passphrase to remember, but you
must copy
~/.codex-sync/age-key.txtto each machine yourself. - Connection test against the bucket.
- Sync scope —
full(everything in the table under What gets synced) orsessions(conversations only). Skip the question with--scope fullor--scope sessions.
Then upload:
codex-sync pushRun codex-sync init with the same passphrase, then pull:
codex-sync init
codex-sync pull --dry-run # optional: preview
codex-sync pullinit verifies the passphrase by decrypting a file from the bucket before it
finishes, so a typo is caught here rather than on pull. If this machine already
has files in ~/.codex, pull shows what would change and offers to back them
up to ~/.codex.backup.<timestamp> first — see
First pull onto a machine that already has files.
make install-launchd # installs the binary, then the agent
make uninstall-launchd # removes the agentThis registers a per-user launchd agent
(~/Library/LaunchAgents/com.codex-sync.daily.plist) that runs
codex-sync pull -q && codex-sync push -q right away, then daily at 03:00 and
at every login. Output goes to ~/Library/Logs/codex-sync.log; when a file
fails, the job exits non-zero and the log says which file and why.
The scheduled job never passes push --force: an unattended run must not be
the thing that deletes remote files. It pulls first anyway, which restores
anything you deleted locally, so deleting a file on every machine is a
deliberate codex-sync push --force.
launchd jobs do not see your shell environment. If you use a custom Codex home,
run CODEX_HOME=/path/to/home make install-launchd — the value is baked into
the agent at install time (re-run the target to change it). There is no
scheduler built into the CLI itself.
codex-sync push # upload local changes
codex-sync pull # download remote changes
codex-sync pull --desktop # …and make new threads visible in the ChatGPT app (quit it first)
codex-sync status # what push would upload
codex-sync diff # local vs remote
codex-sync conflicts # list and resolve conflicts| Command | What it does |
|---|---|
init |
Set up storage, key and scope (interactive wizard) |
push |
Upload local changes; report files removed locally (--force deletes them remotely) |
pull |
Download remote changes; merge, conflict or trash as described below |
desktop refresh |
Make pulled threads visible in the ChatGPT desktop app |
status |
Show pending local changes |
diff |
Show differences between local and remote |
conflicts |
List and resolve .conflict.* sidecars |
paths |
Manage sync paths and exclude filters |
trash |
List (trash list) or restore (trash restore <batch>) remote copies of files a forced push deleted |
reset |
Remove local config, key and sync state (keeps trash/) |
update |
Update to the latest release (verifies checksums.txt) |
changelog |
Show release history |
Every command takes -q / --quiet for scripts. Errors are still printed to
stderr, and a push or pull with any failed file exits non-zero, so
pull -q && push -q stops at the first problem.
codex-sync pull --dry-run # preview downloads, merges, conflicts and removals
codex-sync pull --force # skip the first-pull confirmation prompt
codex-sync pull --no-delete # never move local files to the trash
codex-sync pull --desktop # refresh the desktop app after a successful pull
codex-sync push --force # also delete the remote copies of files deleted locally
codex-sync init --passphrase # re-enter the passphrase only (keeps storage config)
codex-sync init --force # start over: overwrite config and key
codex-sync init --scope sessions # conversations only
codex-sync conflicts --list # just list
codex-sync conflicts --keep local | remote # resolve all one way
codex-sync reset # remove config.yaml, age-key.txt, state.json
codex-sync reset --remote # …and delete every object in the bucketreset never touches ~/.codex and never touches ~/.codex-sync/trash/, so
files an earlier pull removed stay recoverable. Run codex-sync init afterwards
to set up again.
update and changelog read this repository's GitHub Releases. Until the first
release exists they print a build-from-source hint
(git pull && make build && make install) instead of failing.
codex-sync paths # list sync paths and exclude filters
codex-sync paths add <path> # add a path under ~/.codex
codex-sync paths remove <path> # stop syncing a path
codex-sync paths exclude <glob> # skip a glob pattern inside a synced directory
codex-sync paths unexclude <glob> # remove a glob filter
codex-sync paths reset # back to the defaultsExcludes are globs matched against paths relative to ~/.codex and can also be
edited directly in ~/.codex-sync/config.yaml:
exclude:
- "*.tmp"
- "attachments/**"
- "skills/**/node_modules/**"The scope chosen at init is a ceiling: under sessions scope, paths add
rejects a path outside the conversation set rather than silently widening it.
Path (under ~/.codex) |
Scope | Notes |
|---|---|---|
sessions/, archived_sessions/ |
sessions | conversations (rollout files; the source of truth) |
session_index.jsonl |
sessions | thread names — merged, never overwritten |
history.jsonl |
sessions | prompt history — merged, never overwritten |
attachments/ |
sessions | files you attached to threads |
config.toml |
full | providers, MCP servers, project trust |
rules/, skills/, memories/, AGENTS.md |
full |
| Scope | Syncs | Use when |
|---|---|---|
full (default) |
everything in the table above | you want config, rules, skills and memories mirrored too |
sessions |
the rows marked sessions only | you just want conversations to continue across machines |
Never synced, even if you add a parent directory to the sync paths:
auth.json and installation_id (your login and device identity), every
*.sqlite* / *.db* file (Codex rebuilds them from the rollout files),
plugins/, packages/, cache/, logs, worktrees and other runtime state, and
*.conflict.* sidecars.
Home directories are portable: cwd fields inside rollout, history and index
files, and paths in config.toml / AGENTS.md, are rewritten to a ${HOME}
token on upload and resolved back on pull, so two machines with different
usernames still work.
Uploads files whose content changed since the last sync. A file that still has
a live .conflict.* sidecar is skipped and reported as an error until you
resolve it with codex-sync conflicts; the sidecar itself is never uploaded.
Files deleted locally are not deleted remotely by default. A stale
checkout, a restored backup or a half-configured sync_paths would otherwise
erase the copy every other machine pulls from. Push lists them instead:
2 file(s) deleted locally are still in storage:
• sessions/rollout-2026-09-12.jsonl
• memories/old-note.md
Run codex-sync push --force to delete them remotely too.
push --force deletes them, but still refuses to remove an object that
another machine has replaced since your last sync — that file is reported as a
conflict and left in storage. Pull it first, then push again. Each object's
version is re-read immediately before its delete, so the window in which a
device uploading during your push can lose its copy is a single round trip.
Where the provider supports it (S3, R2, GCS, and WebDAV servers that honour
If-Match), the delete is also sent conditionally on that version.
Storage that reports no version at all — some WebDAV servers omit ETags — can only be guarded by timestamps, and those deletes are listed separately:
1 file(s) were deleted remotely without a version check:
• memories/old-note.md
Your storage reports no version for these objects, so a copy another
device uploaded in the last moments may have been removed with them.
Those checks narrow the race with another device but cannot close it, so
every object a forced push removes is copied to _trash/<batch>/ in the same
bucket first, still encrypted. A delete whose copy cannot be written does not
happen at all:
✓ Copies of the 2 deleted file(s) are in _trash/20260920-141500Z/ on the remote.
They stay until you remove them or a bucket lifecycle rule expires them.
Those copies are outside the sync set: pull never downloads them, and a bucket holding nothing else still counts as empty, so it cannot delete anything locally. To undo a deletion:
codex-sync trash list # batches, with counts and sizes
codex-sync trash restore 20260920-141500Z # copy them back to their keys
codex-sync pull # bring the files down againRestoring skips any file another device has re-created since — that newer
version wins — and reports what it left alone. Nothing prunes the recycle bin
automatically; delete old batches yourself, or give the _trash/ prefix a
lifecycle rule (R2, S3 and GCS all support expiry by age) so copies age out
after, say, 30 days. reset --remote removes them along with everything else.
- New and changed remote files are downloaded.
- Both sides changed → conflict. The local file is kept and the remote copy
is saved next to it as
<file>.conflict.<timestamp>. Sidecars are local only: never uploaded, tracked, or removed by a later pull. session_index.jsonlandhistory.jsonlare merged, not conflicted: the remote and local copies are unioned (by thread id, latestupdated_atwins; by distinct line ordered byts), written back locally, and pushed as the union next time. Both machines converge byte-for-byte.- Files that vanished from the remote (deleted or archived on the other
machine) are moved to
~/.codex-sync/trash/<timestamp>/— but only when unchanged locally since the last sync. Locally modified files stay put and are reported.--no-deletedisables this,--dry-runpreviews it. Nothing references the trash, so old batches are safe to delete. - An empty remote never removes anything.
- Pull writes are atomic and stay inside
~/.codex. Each file is written to a temporary file and renamed into place, so an interrupted pull leaves either the old file or the new one. A path that crosses a symlink is refused and reported rather than followed, which matches push: it skips symlinks instead of uploading what they point at.
codex-sync conflicts # interactive
codex-sync conflicts --list # just list
codex-sync conflicts --keep local # keep every local version
codex-sync conflicts --keep remote # keep every remote versionInteractive keys: l keep local, r keep remote, d show diff, s skip, q quit. Resolving a conflict removes the sidecar; the next push publishes whichever version you kept.
When ~/.codex already has content, pull:
- shows what would be overwritten, kept, merged or downloaded;
- asks whether to back up, overwrite or abort;
- on back up, copies the existing files to
~/.codex.backup.<timestamp>first. The backup holds the same set of files a push would upload, soauth.json, the SQLite databases and anything you excluded stay out of it.
pull --dry-run shows the preview without changing anything; pull --force
skips the prompt (for scripts).
Why this step exists. The ChatGPT desktop app keeps its own thread catalog. After a one-time full build it only looks at threads newer than the last one it saw, so a thread that arrives via sync — whose timestamps are older — never appears in the sidebar on its own. Codex itself never re-reads the synced index either, so pulled threads also show up unnamed in the CLI.
What to do. Quit the ChatGPT app, then either:
codex-sync pull --desktop # pull, then refresh
codex-sync desktop refresh # refresh only, after an earlier pullRelaunch the app and the pulled threads appear, with their names.
What the refresh does, in order:
- Backs up the Codex databases and
session_index.jsonlto~/.codex-sync/db-backup-<timestamp>/(--no-backupskips this). - Runs the app's own engine once so it indexes every rollout on disk.
- Copies thread names from the synced
session_index.jsonlinto the engine database for threads that have none (--no-namesskips this). - Schedules the app's full catalog sweep for its next launch.
Good to know:
- It refuses to run while the ChatGPT app or any
codexprocess is open, since they hold the databases. Detection compares each process's executable name, so an app bundle installed under a path containing spaces is found too.pull --desktopstill completes the pull in that case, then reports the running app and exits non-zero — sopull --desktop && pushstops there; quit the app and runcodex-sync desktop refresh. - It is safe to run repeatedly.
- The engine used is the ChatGPT app's bundled one;
--codex-binor$CODEX_BINoverride it. A different engine version may migrate every Codex database, which is why all of them are backed up (except the engine's log store). - Backups accumulate — each run writes a full copy, well over 100 MB with a
large history — and nothing references them, so old
db-backup-*directories are safe to delete.
Wrong passphrase on a new machine. init verifies the passphrase against
the bucket and offers to retry; afterwards, re-enter it without redoing the
storage setup:
codex-sync init --passphraseForgot the passphrase. It is never stored anywhere, and the encrypted files cannot be recovered without it. Start over:
codex-sync reset --remote # delete remote files and local config/key/state (trash/ kept)
codex-sync init # set up again with a new passphrase
codex-sync push # re-upload from this machineA thread I continued on both Macs came back as a conflict. Expected: two
machines appended to the same rollout file between syncs. Pick a side with
codex-sync conflicts; the other transcript is in the sidecar. Avoid resuming
the same thread on two machines between syncs.
Pulled threads are missing from the desktop app. See
Seeing pulled threads in the desktop app.
If desktop refresh says the app is running, quit it (and any codex process)
and run it again.
The launchd job stopped syncing. Check ~/Library/Logs/codex-sync.log;
the last lines name the file that failed and why. An unresolved conflict makes
push fail until you run codex-sync conflicts.
Getting back a file that pull removed. Look in
~/.codex-sync/trash/<timestamp>/; files keep their relative path.
Same model as claude-sync: gzip → age (X25519 / ChaCha20-Poly1305), encrypted
locally before upload, so the storage provider only sees ciphertext and
filenames. Passphrase keys are derived with Argon2id and the fixed salt
sha256("codex-sync-v1"), so the same passphrase gives the same key on every
machine — and a different key than claude-sync would derive. Config, key and
state live in ~/.codex-sync/ with 0600/0700 permissions; note that the
storage credentials in config.yaml are stored in plaintext there.
Details, threat model and the inherited audit: docs/security.md and SECURITY-AUDIT.md. To report a vulnerability, see SECURITY.md.
- Pulled threads do not appear in the ChatGPT desktop app, and carry no name in
the CLI, until
codex-sync desktop refresh(orpull --desktop) runs with the app quit. - Do not resume the same thread on two machines between syncs; you get a conflict sidecar instead of a merged transcript.
- Project organization, automations and the memories database live only in SQLite and are not synced.
- macOS only for now: the desktop refresh and the launchd scheduler are macOS-specific, and the sync commands are untested elsewhere.
- No pre-built binaries or packages yet — build from source.
Bug reports, questions and pull requests are welcome. See CONTRIBUTING.md for the build/test workflow and CLAUDE.md for an architecture tour; the design rationale is in docs/specs/2026-09-15-codex-sync-design.md.
make test # run the tests
make check # gofmt, go vet, go test -short (what the pre-commit hook runs)
make setup-hooks # install the pre-commit hookMIT — see LICENSE. codex-sync is a fork of claude-sync; see NOTICE for the fork point and attribution.