Move your Codex work safely between personal machines — chats, projects, configuration and local state — with guarded handoff, conflict handling, verified backups and recovery.
Important
Validated in practice Windows → Windows only. macOS is supported in code and CI, but an end-to-end handoff on real macOS machines has not been validated.
Codex keeps important working state on your machine. Putting .codex into
Dropbox, OneDrive or Syncthing is not enough: Codex may still be writing to it,
the same chat may be continued differently on two machines, and an interrupted
overwrite can destroy the very copy you needed. codexSync treats moving that
state as a guarded handoff, not as ordinary file synchronisation.
- Hands your work over between machines — one click, or on its own when Codex closes: settings, chats and projects go to the cloud folder, the next machine loads them, and each knows what the other handed off. → Synchronisation
- Carries chats and projects — chat history, chat names and project bindings arrive where Codex looks for them, even when a project folder has another path on the other machine. → Projects and chats
- Never merges two histories — every session branch is classified; a chat continued on both machines keeps one whole copy, by your rule or your choice, and the other is saved. → Sessions
- Backs up before every overwrite and recovers from an interrupted write — lock, journal, verified backup. → Backups and recovery
- Guards the global state with verified snapshots taken while Codex runs,
written only outside
.codex. → Guardian - Can run on its own — the handoff watcher, copies of
.codexand periodic snapshots are ordinary tasks of your OS. → Automation
Neither an integration with Codex internals nor a real-time sync: what it does not do.
- Local-first. codexSync has no service of its own: shared state goes only through the folder you choose.
- Your sign-in never travels.
auth.jsonand other credential files are never copied, at any depth. - Writes only while Codex is closed. When that cannot be determined, nothing is written.
- Nothing is replaced without a verified backup, and every write is journaled, so an interrupted one can be resumed or rolled back.
Found a security or data-safety problem? See SECURITY.md.
Windows, no Python needed: download codexsync-gui-…-windows-amd64.zip
from Releases, unpack it and
run codexsync-gui.exe. It is the command line too.
With Python 3.11+, on Windows or macOS:
pip install "codexsync[gui]" # the window and the command line
codexsync-gui # the first start sets up config.toml with you
pip install codexsync # the command line only, no dependencies
codexsync init-config --output config.toml
codexsync -c config.toml doctorFrom source, and the first run step by step: installing and getting started.
| Overview | How it works, install, first run, design principles, platforms |
| The window | All eleven screens with screenshots |
| Command line | Every command, global options, exit codes |
| Configuration | config.toml section by section, automation |
| Synchronisation | plan and sync: comparison, conflicts, direction, deletions |
| Guardian | Snapshots of the global state, quarantine, restore, a new baseline |
| Sessions | Session branches across machines, working set, mirror, index |
| Projects and chats | Chat bindings, repair after a handoff, moving a project |
| Backups and recovery | Backups, restore, interrupted mutations |
Every page in one place: docs/. For contributors: developer documents. Release notes: CHANGELOG.md.
0.2 — the first release with the window (codexsync[gui] or codexsync-gui.exe)
next to the command line. A few runtime behaviours are deliberately left unused
until a controlled experiment records them — see
what is not proven yet.
Dual-licensed: open source under GPL-3.0-or-later (LICENSE), with
a commercial path described in COMMERCIAL_LICENSE.md.
Contributions are accepted under CONTRIBUTING.md and
CLA.md.