codex-thread-sync

中文说明

codex-thread-sync is a Windows-first tool for moving Codex conversations between machines. It can publish local Codex threads into a shared session store, import selected remote threads back into the local Codex app, and keep authorized projects or threads in sync from a tray GUI.

The recommended v0.1.0 setup is Folder mode: put the session store inside a folder that is already synchronized by Seafile, OneDrive, Baidu Netdisk, Tianyi Cloud, Syncthing, Dropbox, or a similar sync client. Git mode is also supported for users who prefer a private GitHub repository. NFS and SMB are reserved backend names in this release; they behave like Folder mode and expect you to mount the share yourself.

v0.1.0 is an early public release. It is designed for personal multi-device Codex usage on Windows. The store schema is intentionally new and old experimental store layouts are not migrated. If you tested an earlier build, delete and rebuild the old session store before using this release.

Codex conversations can contain source code, file paths, prompts, command output, secrets, and business context. codex-thread-sync does not encrypt the session store.

Use a private Git repository or a private encrypted sync folder. Do not publish the session store to a public repository. Review your sync provider's retention, sharing, and encryption settings before enabling automatic publishing.

• Windows tray GUI built with Tauri.
• Portable CLI: codex-thread-sync.exe.
• Optional bundled MinGit for Git mode, so target machines do not need Git or Rust installed.
• Folder backend for external sync drives.
• Git backend for clone, pull, commit, and push.
• Reserved NFS and SMB backend names, currently handled like Folder mode.
• Project registry and per-machine project bindings.
• Thread catalog with local/remote/imported/update/conflict states.
• Manual import, rebuild index, project binding, and Codex launch.
• Opt-in automation for project/thread publish and import.
• Provider validation before import/rebuild to avoid writing threads with the wrong Codex provider.
• Store schema v3 with immutable machine-owned turn fragments.

Download the Windows portable ZIP from the release, extract it, then run:

Start-GUI.cmd

or:

.\codex-thread-sync-gui.exe

The GUI stores its config under:

%USERPROFILE%\.codex-thread-sync

Codex itself remains under:

%USERPROFILE%\.codex

Folder mode lets your existing sync client move the session store between machines. Good examples include Seafile, OneDrive, Baidu Netdisk, Tianyi Cloud, Syncthing, Dropbox, Nutstore/Jianguoyun, or any other tool that keeps one directory synchronized.

1. Create a shared folder, for example:

D:\Seafile\Code\codex-session-store

2. In the GUI, open Settings.
3. Set Repository to Folder.
4. Set Store checkout to the shared folder path.
5. Set a unique Machine ID, for example desktop-a or laptop-b.
6. Save settings.

On the machine that already has Codex history, run Scan & Publish or enable project-level Auto publish. Wait for your sync client to upload the changed files.

On another machine, point Store checkout to the synchronized copy of the same folder, wait for the sync client to finish downloading, then open Projects and bind each project to the local checkout path on that machine.

Folder mode does not require Git, SSH, or Rust.

Git mode is useful when you want explicit history, private GitHub storage, or git pull/git push as the transfer layer. Use a private repository for the session store.

Example:

sync_backend = "git"
session_store_repo_url = "git@github.com:your-name/codex-session-store.git"
machine_id = "desktop-a"

The portable package can include MinGit. When git_command is not configured, the tool searches for bundled Git next to the executable before falling back to git from PATH.

For SSH remotes, the CLI and GUI use StrictHostKeyChecking=accept-new unless GIT_SSH_COMMAND is already set. The first GitHub host key is accepted automatically for non-interactive operations, and Git output is streamed into the terminal or Activity view.

nfs and samba are reserved backend names in v0.1.0. They currently behave like Folder mode:

• the app reads and writes session_store_checkout;
• your operating system or another tool mounts/synchronizes that path;
• the app does not configure credentials, mount points, NFS exports, or SMB shares.

Use them only when the share is already mounted and behaves like a normal directory.

Before importing a thread on a target machine:

1. Make sure the target project folder exists locally.
2. Open that folder once in Codex so Codex registers it as a project.
3. Close Codex before importing or rebuilding the index.
4. In the GUI, bind the project to the local folder in Projects.
5. Import the thread from Threads, or run the CLI import command.

The tool blocks import when the target folder is missing or when Codex has not registered that folder as a project. This avoids creating threads that exist on disk but do not appear in the Codex project list.

Codex stores a model_provider in its local files and SQLite index. If the provider name is wrong, imported conversations may not appear correctly.

By default, codex-thread-sync follows model_provider from:

%USERPROFILE%\.codex\config.toml

If Codex has no explicit provider, the tool falls back to openai. You can set canonical_provider in config.toml only when you intentionally want to override this behavior.

Run this on a new machine before importing:

.\codex-thread-sync.exe provider-check

The GUI also surfaces provider problems at startup and blocks import/rebuild when the provider is invalid.

Automation runs from the Windows tray app. Closing the main window hides it to the tray; choose Exit from the tray menu to stop it.

Automation is opt-in:

• global automatic sync is off by default;
• project Auto publish is off by default;
• project Auto import is off by default;
• thread rules can include or pause individual threads;
• thread rules override project settings.

The default interval is 60 seconds. Settings enforces a 60 second minimum to avoid excessive polling of Git repositories or sync folders.

Each cycle:

1. refreshes the store;
2. scans only authorized projects or included thread IDs;
3. publishes completed local turns;
4. imports remote updates only while Codex is closed.

Automation never starts or closes Codex by itself.

The GUI and CLI share the same Rust core. Most work can be done without the GUI.

.\codex-thread-sync.exe provider-check
.\codex-thread-sync.exe pull-store
.\codex-thread-sync.exe scan
.\codex-thread-sync.exe sync
.\codex-thread-sync.exe initialize-projects
.\codex-thread-sync.exe catalog --json
.\codex-thread-sync.exe list-threads
.\codex-thread-sync.exe import --thread <thread_id>
.\codex-thread-sync.exe rebuild-index
.\codex-thread-sync.exe automation --once

import --thread <id> uses the thread's bound target folder or original cwd when possible. Pass --cwd when the target machine uses a different path:

.\codex-thread-sync.exe import --thread 019e... --cwd D:\Seafile\Code\openwrt

Default config path:

%USERPROFILE%\.codex-thread-sync\config.toml

Example:

sync_backend = "folder"
machine_id = "desktop-a"
session_store_checkout = "D:\\Seafile\\Code\\codex-session-store"

See config.example.toml for a fuller example.

For compatibility, an existing %USERPROFILE%\.codex\codex-thread-sync.toml is still loaded when the new config file does not exist.

GUI state is stored in:

%USERPROFILE%\.codex-thread-sync\gui-state.json

It contains project bindings, thread rules, automation settings, pending imports, recent operation timestamps, and UI preferences. Core sync settings stay in config.toml.

v0.1.0 uses store schema v3. Completed turns are written as immutable machine-owned JSONL fragments:

threads\<thread-id>\machines\<machine-id>\turns\<turn-id>.<content-hash>.jsonl

This avoids multiple machines rewriting the same events.jsonl, which is especially important for Seafile, OneDrive, NFS, SMB, and other shared-folder backends.

If two machines create different content for the same turn_id, both fragments are kept. The thread is marked as a conflict and automatic publish/import pauses for that thread until it is handled manually.

Development requires Rust, Node.js, npm, and the Windows toolchain needed by Tauri.

cargo fmt --check
cargo test
npm ci
npm run build:ui
npm run tauri:build

Build the portable package:

.\scripts\Bundle-Windows.ps1 -IncludeGui -Zip

The output is written to:

dist\codex-thread-sync-portable
dist\codex-thread-sync-portable.zip
dist\SHA256SUMS.txt

See CHANGELOG.md.