When You Need It

After switching model_provider, older Codex sessions may disappear from Desktop or /resume. The sessions are usually still present, but their rollout, SQLite, or project-visibility metadata still points to the previous Provider.

Use this tool when:

• switching between an official subscription (whose internal Provider is openai) and a custom relay;
• switching configurations that must use different model_provider IDs;
• rollout and SQLite Provider or model metadata has become inconsistent; or
• you want changes to config.toml, SQLite, or its WAL to trigger synchronization automatically.

If all of your relays can reliably reuse one model_provider ID and history remains visible, using that shared ID is simpler and no synchronization is needed. This project is mainly useful when Provider IDs cannot be unified or when switching between official and custom Providers.

The tool does not sign in, manage accounts, or switch authentication. Switch Provider using your normal workflow first, then synchronize history.

What It Updates

• Rollout metadata under ~/.codex/sessions and ~/.codex/archived_sessions.
• Codex SQLite thread records, including layouts where SQLite is stored outside Codex Home.
• Project-visibility path information and related model metadata when required.
• Managed backups before each synchronization, with restore and pruning support.
• Large rollout files in place when safe, with automatic fallback to a full safe rewrite.
• Automatic CLI synchronization after config.toml, SQLite, or WAL changes.

Quick Start

Windows GUI

For normal Windows use, download and extract CodexProviderSync.exe from Releases:

1. Open CodexProviderSync.exe.
2. Click 刷新 (Refresh).
3. Select the target Provider.
4. Click 立即同步 (Sync Now).

The GUI keeps backups and displays the synchronization result. It checks for a stable release in the background on the first launch of each local day, with a 10-second lookup deadline. Manual update checks remain available. Execution logs are stored under %AppData%\codex-provider-sync\logs.

The Windows GUI supports a separate SQLite Home on the Windows filesystem for each Codex Home. WSL UNC paths such as \\wsl.localhost\... and \\wsl$\... are diagnostic-only; the GUI reports the safety boundary and disables synchronization and restore. Run the CLI inside WSL for a Windows Codex Home plus WSL SQLite Home layout.

The Windows executable is currently unsigned, so browser downloads may trigger a SmartScreen warning. Download it only from this project's Releases and verify the matching SHA-256 when needed.

See README_GUI_ZH.md for the full Windows guide. A self-built Avalonia macOS app is also available; see the English macOS GUI guide.

CLI

The CLI requires Node.js 16+:

npm install -g git+https://github.com/Dailin521/codex-provider-sync.git
codex-provider status
codex-provider sync

Common commands:

Command	Purpose
codex-provider status	Inspect the current Provider, rollout files, SQLite, and project visibility
codex-provider sync	Synchronize history to the current Provider without changing authentication
codex-provider switch <provider-id>	Change the root model_provider, then synchronize
codex-provider restore <backup-dir>	Restore a selected backup
codex-provider prune-backups --keep 5	Keep only the five newest managed backups
codex-provider watch	Watch config, SQLite, and WAL changes and synchronize automatically
codex-provider watch --once	Exit after the first change is synchronized successfully

switch accepts --model <NAME> to set the root model explicitly, or --keep-root-model to change only the Provider. All main commands accept --codex-home <PATH> and --sqlite-home <PATH>.

SQLite Home precedence is: CLI override, root-level sqlite_home in config.toml, CODEX_SQLITE_HOME, then <Codex Home>/sqlite. The legacy <Codex Home>/state_5.sqlite fallback is enabled only for the default layout. An explicit SQLite Home never falls back to a stale database under Codex Home.

For a Windows Codex Home with app-server and SQLite running in WSL, invoke the CLI from WSL:

codex-provider status --codex-home /mnt/c/Users/you/.codex --sqlite-home /home/you/.codex/sqlite
codex-provider sync --codex-home /mnt/c/Users/you/.codex --sqlite-home /home/you/.codex/sqlite

status reports the effective SQLite Home and its source. If an explicit location has no state_5.sqlite, read-only status reports the diagnostic while write operations fail. If a database is deleted from the default layout, restore can rebuild it at its original default location from backup metadata. New metadata v2 backups record the separate SQLite Home. Restoring a v2 backup to a different SQLite Home is rejected unless relocation is explicitly confirmed; the CLI requires --sqlite-home, --allow-sqlite-home-relocation, and --no-config so the restored config cannot point Codex back to the source SQLite Home.

Node.js 24+ uses the built-in node:sqlite module. Older supported Node.js releases use the optional better-sqlite3 dependency.

Business Automation API (experimental v0.4)

The v0.4 Windows Release build also contains CodexProviderSync.Automation.exe and automation-protocol-v0.4.schema.json. This one-shot process interface uses the same Application use cases as the Windows GUI. Each invocation emits exactly one protocol 0.4 JSON document on stdout and sends diagnostics to stderr.

Command	Purpose
describe	Describe protocol capabilities and safety requirements
status	Read status and diagnostics
plan --operation sync|switch|restore|prune	Create a plan for a selected write operation
sync	Plan or explicitly apply synchronization
switch	Plan or explicitly apply a Provider/model switch and synchronization
restore	Plan or explicitly apply backup restoration
prune	Plan or explicitly prune managed backups

Every write command is dry-run by default and returns a plan without modifying a target. Mutation requires --apply, a plan file containing only the data object from the plan response, and that object's exact lowercase SHA-256 digest:

.\CodexProviderSync.Automation.exe describe
.\CodexProviderSync.Automation.exe status --codex-home C:\isolated\.codex
.\CodexProviderSync.Automation.exe sync --codex-home C:\isolated\.codex --provider openai
$planResponse = .\CodexProviderSync.Automation.exe plan --operation sync --codex-home C:\isolated\.codex --provider openai | ConvertFrom-Json
$planResponse.data | ConvertTo-Json -Depth 100 -Compress | Set-Content -LiteralPath C:\isolated\sync-plan.json -Encoding utf8NoBOM
$planDigest = $planResponse.data.digest
.\CodexProviderSync.Automation.exe sync --codex-home C:\isolated\.codex --provider openai --apply --plan C:\isolated\sync-plan.json --plan-digest $planDigest

Plans expire, bind normalized inputs and target state, and are single-use through a durable ledger. The default ledger is <Codex Home>\tmp\provider-sync-automation-ledger. Every path argument must be absolute and may not traverse a symbolic link or reparse point. Automation also rejects direct access to auth.json. The protocol remains experimental before 1.0; compatibility is not promised outside protocol family 0.4.

Safety and Limitations

Before each sync or switch, the tool creates a backup under:

~/.codex/backups_state/provider-sync/<timestamp>

• It does not modify messages, session titles, authentication, auth.json, or updated_at.
• It does not copy configuration or session files between devices; it only repairs metadata in the current Codex Home.
• If SQLite is in use, close Codex, Codex App, and app-server before retrying.
• A Windows process that resolves SQLite Home through a WSL UNC path reports a dedicated safety diagnostic and stops immediately. Continue inside that WSL distribution with the Linux /home/... path.
• If a live session locks a rollout file, the tool skips that file and continues. Run sync again after the session ends for a complete update.
• Sessions containing encrypted_content may become visible across Providers/accounts but still fail to continue or compact with invalid_encrypted_content.
• Codex Desktop currently shows only the latest 50 sessions on its first page. If /resume can see a session but the project view cannot, inspect the first page / ranks diagnostics. This tool does not alter timestamps to bypass that upstream limit.

Documentation

• Windows GUI guide
• macOS GUI guide
• v0.4.0 Release Notes (Draft)
• v0.4 Automation execution plan
• 中文说明
• AI / Agent guide
• Contributing guide

Development

git clone https://github.com/Dailin521/codex-provider-sync.git
cd codex-provider-sync
npm test
dotnet test desktop/CodexProviderSync.Core.Tests/CodexProviderSync.Core.Tests.csproj
./scripts/test-wsl-unc-safety.sh
pwsh ./scripts/publish-gui.ps1
pwsh ./scripts/run-windows-gui-e2e.ps1
./scripts/publish-gui-macos.sh

Run test-wsl-unc-safety.sh from WSL. It invokes Windows dotnet.exe to verify the safety guard against a real SQLite database on WSL ext4. Run run-windows-gui-e2e.ps1 only on a visible, interactive Windows desktop. The v0.4 implementation commit 7545b5d passed this gate with 40/40 manifest entries covered, 53/53 required scenarios passed, and zero errors or blockers; the evidence gate also verified the published EXE hash, real control events, native dialogs, file/SQLite effects, restart persistence, and GUI-to-Application traces. Relevant later implementation changes require another run. Hidden, skipped, or direct-Application runs are not substitutes.

License

MIT