codex-provider-sync: realigning Codex session providers after a switch

The metadata mismatch that makes an old Codex session look broken

A Codex session carries a provider name in two places: the rollout file on disk and the SQLite chat index. Switch providers with a tool such as CCSwitch and the configuration changes, but the historical records keep the provider they were written with. The README frames the project's entire purpose around that gap: it aligns the provider information in session files and the SQLite chat index with the current configuration, and it describes the result as a metadata consistency problem rather than a broken session. That distinction matters. The README states plainly that it does not guarantee that old sessions from another provider or account can still be continued or compacted, and that it does not touch login, authentication or encrypted content. So the intended user is someone who has already switched providers, sees old sessions that no longer behave, and wants the recorded provider to match reality before investigating anything else. If the provider information is already aligned, the README says there is nothing to do and the next step is to read the actual Codex error.

One Node core, three entry points, and the two write paths

The README describes a single shared Node core behind three entry points: a Windows desktop app, a local Web UI, and a CLI. The Mermaid diagram in the README routes all three into a common operations layer (status, sync, switch, watch, repair, restore) with plan validation, concurrency control, progress and cancellation underneath, and that layer writes to three targets: the Codex config, the session files, and the SQLite index. Backup and restore hang off the operations layer rather than the entry points. The consequence stated in the README is that the entry point changes how you operate the tool, not what the sync produces. The write path is the more interesting design decision. Sync parses only the first line of metadata in each session and aligns the provider in the session file and in SQLite; chat bodies are left alone. If in-place writing conditions are met, including the provider name being the same byte length, the tool rewrites the provider directly without generating a full copy of the session. For other valid first lines it updates the first line, streams the body into a new file, then replaces the original. The README says the tool picks between the two automatically and that you do not need to pad provider names to equal lengths. Speed depends mostly on how many sessions need updating; when provider lengths differ and the history files are large, the body copy adds time, as do backup, pre-write validation, flushing to disk and timestamp restoration. Per-step timings are visible in the operation log.

Installing the codex-provider-sync CLI and running the first sync

The README's local Web UI section gives the npm route, and it requires Node.js 16.20.2 or newer. The global install pulls the currently published CLI and Web version.

npm install -g @dailin521/codex-provider-sync
codex-provider web

The Web UI listens only on 127.0.0.1:8791 by default, so you open a browser on the same machine and complete pairing there. Cross-device use is covered in the Web guide rather than in the README itself. For a terminal workflow, the README's CLI section installs the same npm package and starts with a read-only check before any write:

codex-provider status
codex-provider sync

The README notes that CLI write commands execute directly, so status first is the cheap way to see the current provider, storage paths and sync state. The desktop route is separate: the README points Windows x64 users at the latest release for an installer or a portable ZIP, states that no Node.js is needed, that the build is unsigned, and that the portable version must be fully extracted. macOS and Linux Electron packages are not published. If you already switched providers with an external tool, the daily flow in the README is to open the overview, confirm provider, storage path and sync status, then use preview sync to see the impact or direct sync to execute immediately. The separate provider switch action updates the config and syncs the historical provider but does not change historical models, and custom providers must be configured in advance.

Partial completion, skipped sessions and the limits of undo

The most honest part of the README is what happens when a sync does not finish cleanly. A result of partial completion means some sessions were skipped while their associated index entries were preserved, and the remaining sessions continued processing. The README splits the causes into two groups: format or size problems, which require you to handle the data and preview again, and sessions that are in use or changing, which you retry after the session stops writing. It also states that completed modifications are not automatically rolled back in full. That is the real failure mode to plan for. A sync that half-succeeds leaves you with a mix of aligned and unaligned sessions, and the recovery path is the backup taken before the operation, managed in the backup and restore view, with a default retention of the last two backups. Protected backups are not subject to that count, and no backup is taken when nothing needs changing. The second limitation is stated at the top of the README and is easy to skip past: provider alignment is one condition among several. If a session still fails after sync, the README directs you to the Codex error itself, and suggests returning to the original provider or account, or creating a new session, when encryption or model compatibility is involved.

Where codex-provider-sync sits next to CCSwitch-style switchers

The natural alternative is the provider switcher you already use, CCSwitch being the one the README names. The difference is scope, and it is worth being precise about it. A switcher changes which provider Codex is configured to use; it does not go back and rewrite the provider recorded in sessions that were created under the previous one. codex-provider-sync is built for the second half of that job, and the README treats the two as complementary rather than competing: if you switched with CCSwitch, you open this tool, confirm the current provider is the one you want, and sync. The tool also offers its own switch action, which updates the configuration and then syncs the session files and index, so you can use it as the switcher too. The trade-off is that you are adding a step to every provider change, and the README is explicit that repeating the sync when the provider information is already consistent is pointless. A second, less obvious alternative is doing nothing and reading the Codex error first. The README's own troubleshooting order supports this: if the metadata is already aligned, the failure is elsewhere, and syncing again will not change the outcome.

Maintenance, release cadence and what the MIT licence covers

The repository is not archived, and the last push was on 2026-09-15, the same day as the v1.0.3 release. The three releases listed are close together: v1.0.1 on 2026-09-11, v1.0.2 on 2026-09-11, and v1.0.3 on 2026-09-15. Their titles point at Windows update behaviour and sync status fixes, which tells you where the recent churn has been. The repository ships a Windows solution file, an Electron desktop workspace, a web workspace and packages, and the README's contributor section says the old .NET Windows and macOS implementations are still maintained as compatibility implementations, so there is more than one code path to keep in mind when reading issues or PRs. Source development targets Node 24 and runs npm ci, an architecture check, tests, a web build and a desktop build; the README warns that a successful build is not the same as release acceptance on every platform. Licence is MIT, which permits commercial and private use and modification provided the copyright notice and permission notice are retained; this is a description of the licence text, not legal advice, and the LICENSE file is the authority. One packaging caveat the README states directly: the Windows desktop build is unsigned, so Windows will warn on first run.

Editorial conclusion

Adopt it if you switch Codex providers with CCSwitch or similar tools and want old sessions to carry the current provider name in both the rollout files and the SQLite index, and you accept that provider alignment is only one condition for a session to resume. Do not adopt it expecting it to fix login, encrypted content or model compatibility, and do not expect a macOS or Linux desktop build: only the Windows x64 desktop package and the npm CLI/Web are published. Before trusting it on real history, run codex-provider status, then codex-provider sync, and confirm the pre-change backup appears in the backup list so codex-provider restore <backup-dir> has something to point at.

Frequently asked questions

Official sources

1. Dailin521/codex-provider-sync on GitHub
2. Issues
3. License: MIT
4. README
5. Releases