wehub-resource-sync
244 lines
8.5 KiB
Markdown
244 lines
8.5 KiB
Markdown
<div align="center">
|
|
|
|
# codex-provider-sync
|
|
|
|
### Keep Codex history visible after switching between providers
|
|
|
|
[](https://github.com/Dailin521/codex-provider-sync/actions/workflows/ci.yml)
|
|
[](https://github.com/Dailin521/codex-provider-sync)
|
|
[](https://nodejs.org/)
|
|
[](../LICENSE)
|
|
[](https://linux.do/)
|
|
|
|
English | [中文](../README.md)
|
|
|
|
</div>
|
|
|
|
## What It Solves
|
|
|
|
Codex session visibility can break after you switch `model_provider`.
|
|
|
|
Typical symptom:
|
|
|
|
- old sessions are visible under one provider
|
|
- then disappear after switching to another provider
|
|
- `codex resume` and Codex App may disagree because session metadata is stored in both rollout files and SQLite
|
|
|
|
`codex-provider-sync` fixes that by updating both:
|
|
|
|
- `~/.codex/sessions` and `~/.codex/archived_sessions`
|
|
- the Codex state database, usually `~/.codex/sqlite/state_5.sqlite`
|
|
|
|
Older Codex layouts may still use `~/.codex/state_5.sqlite`; the tool detects the active location and reports it in `codex-provider status`.
|
|
|
|
## GUI For Windows
|
|
|
|
If you want a normal Windows app instead of Node/npm, download `CodexProviderSync.exe` from Releases.
|
|
|
|
The GUI app:
|
|
|
|
- scans the current `.codex` home
|
|
- shows provider distribution from rollout files and SQLite
|
|
- lets you choose a target provider from detected and saved providers
|
|
- can optionally update root `model_provider` in `config.toml`
|
|
- keeps the latest 5 managed backups by default, with a configurable retention count
|
|
- can manually clean old managed backups from the app
|
|
- can restore from backup without using a terminal
|
|
|
|
For GUI-specific usage notes, see [README_GUI_ZH.md](README_GUI_ZH.md).
|
|
|
|
## Install
|
|
|
|
```bash
|
|
npm install -g git+https://github.com/Dailin521/codex-provider-sync.git
|
|
```
|
|
|
|
Requirements:
|
|
|
|
- Node.js `16+`
|
|
- Node.js 24+ uses the built-in `node:sqlite` module; older Node.js releases use the optional `better-sqlite3` dependency.
|
|
- standard `~/.codex` layout
|
|
- Windows is the primary tested target for now
|
|
|
|
For end users, the GUI EXE is the recommended path. The npm CLI remains available for power users and automation.
|
|
|
|
## Quick Start
|
|
|
|
GUI:
|
|
|
|
- download `CodexProviderSync.exe` from Releases
|
|
- open it and click `Refresh`
|
|
- choose the target provider
|
|
- click `Execute`
|
|
|
|
If you already switched auth/provider using your usual method:
|
|
|
|
```bash
|
|
codex-provider sync
|
|
```
|
|
|
|
If you want to change the root `model_provider` and sync history in one step:
|
|
|
|
```bash
|
|
codex-provider switch openai
|
|
codex-provider switch apigather
|
|
```
|
|
|
|
If you want a different automatic backup retention count for one run:
|
|
|
|
```bash
|
|
codex-provider sync --keep 5
|
|
codex-provider switch apigather --keep 10
|
|
```
|
|
|
|
Check current state first:
|
|
|
|
```bash
|
|
codex-provider status
|
|
```
|
|
|
|
Install a Windows double-click launcher (placed on your Desktop by default):
|
|
|
|
```bash
|
|
codex-provider install-windows-launcher
|
|
```
|
|
|
|
Rollback from a backup:
|
|
|
|
```bash
|
|
codex-provider restore C:\Users\you\.codex\backups_state\provider-sync\<timestamp>
|
|
```
|
|
|
|
Clean old managed backups manually:
|
|
|
|
```bash
|
|
codex-provider prune-backups --keep 5
|
|
```
|
|
|
|
## AI Quick Run
|
|
|
|
If you want an AI assistant to handle this in one shot, copy this prompt:
|
|
|
|
```text
|
|
Help me fix Codex session visibility with codex-provider-sync.
|
|
|
|
Steps:
|
|
1. Run `codex-provider status`.
|
|
2. If my current provider is already correct, run `codex-provider sync`.
|
|
3. If I explicitly want to switch provider, run `codex-provider switch <provider-id>` instead.
|
|
4. If `state_5.sqlite` is currently in use, tell me to close Codex / Codex App / app-server and retry.
|
|
5. If sync skips locked rollout files, tell me which files were skipped and remind me to rerun `codex-provider sync` later.
|
|
6. Summarize the final provider counts in rollout files and SQLite.
|
|
```
|
|
|
|
If the user prefers the GUI, the AI can instead guide these steps:
|
|
|
|
1. Open `CodexProviderSync.exe`
|
|
2. Confirm the `.codex` path
|
|
3. Click `Refresh`
|
|
4. Pick the target provider from the list
|
|
5. Enable the config checkbox only if root `model_provider` should also change
|
|
6. Click `Execute`
|
|
7. Read the log panel for backup path, updated rollout files, SQLite rows, and skipped locked files
|
|
|
|
Quick mapping:
|
|
|
|
- inspect only: `codex-provider status`
|
|
- fix visibility under current provider: `codex-provider sync`
|
|
- switch provider and sync: `codex-provider switch openai`
|
|
- install a desktop double-click launcher: `codex-provider install-windows-launcher`
|
|
- roll back a mistake: `codex-provider restore <backup-dir>`
|
|
|
|
## Commands
|
|
|
|
- `codex-provider status`
|
|
- shows current provider, the detected SQLite database path, and provider distribution in rollout files and SQLite
|
|
- `codex-provider sync`
|
|
- syncs history to the current provider
|
|
- `--provider <id>` overrides the target provider
|
|
- if root `model_provider` is missing, it falls back to `openai`
|
|
- `codex-provider switch <provider-id>`
|
|
- updates root `model_provider` in `config.toml`
|
|
- immediately runs a sync
|
|
- `--keep <n>` overrides how many managed backups are retained after the run
|
|
- `codex-provider prune-backups`
|
|
- manually removes older managed backups and keeps the newest `n`
|
|
- `codex-provider restore <backup-dir>`
|
|
- restores a previous backup
|
|
- use `--no-config`, `--no-db`, or `--no-sessions` to skip a restore target
|
|
- `codex-provider install-windows-launcher`
|
|
- creates two files on the Desktop by default
|
|
- `Codex Provider Sync.vbs`: hidden double-click launcher with a result popup
|
|
- `Codex Provider Sync.cmd`: visible console version for troubleshooting
|
|
- use `--dir <path>` to choose another install directory
|
|
- use `--codex-home <path>` to bake a fixed `CODEX_HOME` into the launcher
|
|
|
|
```bash
|
|
codex-provider status
|
|
codex-provider sync
|
|
codex-provider sync --keep 5
|
|
codex-provider sync --provider openai
|
|
codex-provider switch openai
|
|
codex-provider switch apigather
|
|
codex-provider prune-backups --keep 5
|
|
codex-provider install-windows-launcher
|
|
codex-provider install-windows-launcher --dir D:\Tools
|
|
codex-provider install-windows-launcher --codex-home C:\Users\you\.codex
|
|
codex-provider restore C:\Users\you\.codex\backups_state\provider-sync\20260319T042708906Z
|
|
codex-provider status --codex-home C:\Users\you\.codex
|
|
codex-provider sync --codex-home C:\Users\you\.codex
|
|
codex-provider switch apigather --codex-home C:\Users\you\.codex
|
|
codex-provider restore C:\Users\you\.codex\backups_state\provider-sync\20260319T042708906Z
|
|
```
|
|
|
|
## Safety
|
|
|
|
Before each sync, the tool creates a backup under:
|
|
|
|
```text
|
|
~/.codex/backups_state/provider-sync/<timestamp>
|
|
```
|
|
|
|
It also uses:
|
|
|
|
```text
|
|
~/.codex/tmp/provider-sync.lock
|
|
```
|
|
|
|
- It does not replace official `codex`.
|
|
- It does not manage `auth.json` or third-party login tools.
|
|
- It does not rewrite message history, titles, cwd, or timestamps.
|
|
- It keeps the newest 5 managed backups by default; GUI retention settings or CLI `--keep <n>` can override that.
|
|
- Manual cleanup and auto-prune only touch backups created by this tool inside `backups_state/provider-sync`.
|
|
- `Codex Provider Sync.vbs` assumes the `codex-provider` command is already available.
|
|
- If `state_5.sqlite` is in use, close Codex / Codex App / app-server and retry.
|
|
- If `state_5.sqlite` is malformed, the tool reports it as malformed/unreadable and blocks sync; back up, repair, or remove the damaged database before retrying.
|
|
- If a live session keeps one rollout file open, `sync` skips that file and reports it. Rerun later.
|
|
- If history contains `encrypted_content`, switching across providers/accounts may restore visibility only; continuing or compacting those sessions can still fail with `invalid_encrypted_content` because this tool cannot re-encrypt Codex history.
|
|
|
|
## EXE double-click troubleshooting
|
|
|
|
1. Fully extract the release archive before running `CodexProviderSync.exe`.
|
|
2. If no window appears, open PowerShell in the EXE directory and run `./CodexProviderSync.exe`.
|
|
3. Check Windows SmartScreen, Defender, or third-party antivirus blocks.
|
|
4. Check `%AppData%\codex-provider-sync\startup-error.log`; startup exceptions are written there.
|
|
|
|
## For AI Agents
|
|
|
|
For a fuller machine-oriented version, see [AGENTS.md](../AGENTS.md).
|
|
|
|
## Development
|
|
|
|
```bash
|
|
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
|
|
pwsh ./scripts/publish-gui.ps1
|
|
node ./src/cli.js status --codex-home C:\path\to\.codex
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|