codex-provider-sync

Keep Codex history visible after switching Providers

中文 · 日本語 · 한국어 · Web UI guide

What it is

codex-provider-sync is a local metadata-consistency tool for Codex. After changing the root model_provider, older sessions may still be on disk while rollout files, the SQLite thread index, or project metadata still points to the previous Provider. Codex can then hide those sessions from its list, project view, or /resume.

The primary interface is a browser-based Web UI running on localhost. It reuses the same Node.js core service as the CLI and does not reimplement synchronization in the browser.

The tool does not sign you in, manage auth.json, switch accounts, or modify message bodies.

Quick start: Web UI

Requires Node.js 16.20.2 or newer.

From the repository:

npm install
npm run web:build
npm run web:start

Or install the CLI globally:

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

The default address is:

http://127.0.0.1:8791

Options:

codex-provider web --no-open   # do not open a browser automatically
codex-provider web --port 8792 # use another localhost port
codex-provider web --reset-access # invalidate previously paired browsers

The server binds only to 127.0.0.1. Startup opens a short-lived one-time pairing URL; the browser exchanges it for a persistent device credential, while the server stores only its hash. API writes validate the actual loopback Host/Origin and serialize sync, switch, restore, and prune. Storage paths are resolved from server-managed profiles instead of being accepted on every write request.

For a headless server, forward the loopback port and print the one-time pairing link instead of launching a desktop browser:

ssh -L 8791:127.0.0.1:8791 user@server
codex-provider web --no-open

The browser opener is best-effort and never terminates the service if xdg-open or a desktop session is unavailable. Do not expose this service directly to a LAN or the public Internet.

Web UI features

Overview

• Current root Provider and model.
• Rollout distribution under sessions and archived_sessions.
• SQLite threads distribution.
• Rollout/SQLite alignment status.
• Project visibility diagnostics: CWD matches, ranks, and the first-page 50-session limit.
• Warnings for locked rollouts, encrypted_content, SQLite repairs, malformed databases, and WSL UNC safety boundaries.

Chat history

The Chat History page reads rollout JSONL files read-only and never changes local data.

• Browse sessions and open user/agent messages.
• Search titles, project paths, Providers, and message text.
• Filter by Provider, project, and active/archived state.
• Server-side pagination, 50 sessions per page by default.
• Session details show the most recent 200 readable messages.
• Safe, restricted Markdown rendering with code-block support.
• Raw JSONL, tokens, tool-call arguments, and encrypted_content are not returned to the browser.

Sync and switch

• Sync metadata only: use the current root Provider without changing config.toml.
• Switch Provider and sync: update the root model_provider, then synchronize history.
• Model policy: follow the Provider section, keep the current root model, or set a custom model.
• An explicit confirmation dialog reminds you to close Codex CLI, Codex App, and app-server first.

Backups and restore

• Create a metadata v2 backup before every sync or switch.
• Keep the newest five managed backups by default.
• Restore config.toml, SQLite, and rollout metadata independently.
• Show source and target when SQLite Homes differ.
• Require an extra confirmation for SQLite Home relocation and prevent unsafe config/database combinations.

CLI for automation and WSL

The CLI and Web UI call the same src/service.js core logic.

codex-provider status
codex-provider sync
codex-provider sync --keep 5
codex-provider sync --provider openai
codex-provider switch apigather
codex-provider switch apigather --model "MiniMax-M3"
codex-provider switch apigather --keep-root-model
codex-provider prune-backups --keep 5
codex-provider restore C:\Users\you\.codex\backups_state\provider-sync\20260319T042708906Z
codex-provider watch
codex-provider watch --once

All main commands accept --codex-home <PATH> and --sqlite-home <PATH>. For a Windows Codex Home with app-server and SQLite in WSL, run the CLI inside 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

The v0.4 Windows release also includes an experimental one-shot automation package for scripts and AI agents. Its write operations are dry-run by default and require an explicit plan, digest, and --apply before changing data. See the automation quickstart and the protocol design.

Storage and SQLite resolution

SQLite Home precedence is:

1. CLI or GUI override.
2. Root-level sqlite_home in config.toml.
3. CODEX_SQLITE_HOME.
4. <Codex Home>/sqlite.

Only the default layout may check the legacy <Codex Home>/state_5.sqlite. An explicit, configured, or environment-provided SQLite Home never falls back to another database.

Safety and limitations

Before each sync or switch, a backup is created under:

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

• Messages, titles, authentication, auth.json, and updated_at are not modified.
• The tool repairs metadata only within the selected Codex Home; it does not copy sessions between devices.
• If SQLite is locked, close Codex CLI, Codex App, and app-server and retry.
• Locked live rollout files are skipped and can be synchronized after the active session ends.
• Sessions containing encrypted_content may become visible but still fail to continue or compact across Providers/accounts.
• Windows processes cannot safely operate on SQLite through \\wsl.localhost\... or \\wsl$\...; use the corresponding Linux path inside WSL.

Desktop GUI status

The Desktop GUI is deprecated and is no longer the recommended or primary interface. Existing Windows/macOS builds remain available for compatibility, but new features—especially Chat History—are implemented in the Web UI first.

Legacy GUI references:

• Windows GUI guide
• macOS GUI guide

Documentation

• 中文说明
• 日本語
• 한국어
• Web UI guide
• Working principle
• AI / Agent guide
• Contributing guide

Development and tests

git clone https://github.com/Dailin521/codex-provider-sync.git
cd codex-provider-sync
npm install
npm run web:build
npm test
git diff --check

To publish the npm package after authenticating with npm:

npm run publish:npm -- --dry-run
npm run publish:npm -- --otp 123456

The publish script checks the npm login, rebuilds the Web UI, runs tests, previews the package contents, and then publishes the current version. Use NPM_OTP=123456 npm run publish:npm when preferred. The OTP is never written to repository files.

License

MIT