wehub-resource-sync
170 lines
6.0 KiB
Markdown
170 lines
6.0 KiB
Markdown
# AI Operator Guide
|
|
|
|
This file is for AI assistants, coding agents, and automation tools.
|
|
|
|
## Goal
|
|
|
|
Help the user make historical Codex sessions visible again after switching `model_provider`.
|
|
|
|
For normal Windows users, prefer the GUI app when it is available. Use the CLI when:
|
|
|
|
- the user explicitly wants commands
|
|
- the task is automated
|
|
- the GUI EXE is unavailable
|
|
|
|
The tool works by updating both:
|
|
|
|
- rollout metadata under `~/.codex/sessions` and `~/.codex/archived_sessions`
|
|
- SQLite thread metadata in the detected Codex state database, normally
|
|
`~/.codex/sqlite/state_5.sqlite` with legacy fallback to
|
|
`~/.codex/state_5.sqlite`
|
|
|
|
Do not solve this by manually editing rollout files only unless the user explicitly asks for manual intervention.
|
|
|
|
## Preferred Flow
|
|
|
|
Use this order by default:
|
|
|
|
1. If the GUI is available and the user is not asking for terminal commands, open `CodexProviderSync.exe`
|
|
2. Refresh and inspect the current provider plus rollout/SQLite distribution
|
|
3. Decide whether the user needs sync, switch-like behavior, or restore
|
|
4. Execute the action
|
|
5. Report whether the result is complete or partially skipped due to locked files
|
|
|
|
CLI fallback flow:
|
|
|
|
1. Run `codex-provider status`
|
|
2. Read `Current provider`, the displayed SQLite database path, and compare rollout/SQLite distribution
|
|
3. Decide whether the user needs `sync`, `switch`, or `restore`
|
|
4. Run the command
|
|
5. Report whether the result is complete or partially skipped due to locked files
|
|
|
|
## Command Selection
|
|
|
|
Use `codex-provider sync` when:
|
|
|
|
- the user already switched auth/provider using another tool
|
|
- the current `config.toml` root `model_provider` is already correct
|
|
- the user says things like:
|
|
- "make my old sessions visible again"
|
|
- "resync my Codex history"
|
|
- "I already switched provider"
|
|
|
|
Use `codex-provider switch <provider-id>` when:
|
|
|
|
- the user wants to change the root `model_provider`
|
|
- the user wants one command to both switch provider and resync history
|
|
|
|
Use `codex-provider restore <backup-dir>` when:
|
|
|
|
- the user wants to roll back a previous sync
|
|
- the user synced to the wrong provider
|
|
|
|
Use `codex-provider status` only when:
|
|
|
|
- the user asks for inspection only
|
|
- you need a safe first step before deciding what to do
|
|
|
|
## GUI Selection
|
|
|
|
Use the GUI app when:
|
|
|
|
- the user wants a double-click tool
|
|
- the user does not want to install Node/npm
|
|
- the user wants to visually inspect providers and backups
|
|
|
|
GUI mapping:
|
|
|
|
- `Refresh` = inspect current status
|
|
- `Execute` without config checkbox = `sync --provider <selected>`
|
|
- `Execute` with config checkbox = switch-like behavior
|
|
- `Restore Backup` = restore a previous backup
|
|
- backup retention defaults to 5 and can be customized in the GUI
|
|
- `Clean Old Backups` = prune managed backups down to the selected retention count
|
|
|
|
## Important Behavior
|
|
|
|
- `sync` uses the current root `model_provider` from `~/.codex/config.toml`
|
|
- if root `model_provider` is missing, `sync` falls back to `openai`
|
|
- `switch` changes root `model_provider`, then runs a sync
|
|
- built-in `openai` is always valid
|
|
- custom providers must already exist in `config.toml`
|
|
- the tool does not log the user in and does not manage `auth.json`
|
|
- sync and switch create a backup first, then automatically prune older managed backups
|
|
- backup pruning only touches backups created by this tool under `backups_state/provider-sync`
|
|
|
|
## Error Handling
|
|
|
|
If the output says `state_5.sqlite is currently in use`:
|
|
|
|
- tell the user to close Codex, Codex App, and app-server
|
|
- then rerun the same command
|
|
|
|
If sync reports `Skipped locked rollout files`:
|
|
|
|
- treat the sync as mostly successful
|
|
- explain that the active session still holds one or more rollout files open
|
|
- tell the user to rerun `codex-provider sync` after that session ends if they want a full rewrite
|
|
|
|
If `switch <provider-id>` fails because the provider is missing:
|
|
|
|
- tell the user to define it in `config.toml` or switch via their existing provider tool first
|
|
- then run `codex-provider sync`
|
|
|
|
## Safe Defaults
|
|
|
|
- default Codex home: `~/.codex`
|
|
- detect the SQLite DB before reasoning about SQLite counts; recent Codex uses
|
|
`~/.codex/sqlite/state_5.sqlite`, while older layouts may use
|
|
`~/.codex/state_5.sqlite`
|
|
- prefer `status` before destructive-looking operations, even though this tool only edits metadata
|
|
- by default the tool keeps the most recent 5 managed backups
|
|
- use GUI retention settings or CLI `--keep <n>` when the user wants a different retention count
|
|
- do not edit `state_5.sqlite` or rollout files manually if the tool can do it
|
|
- GUI settings live in `%AppData%\codex-provider-sync\settings.json`
|
|
|
|
## Recommended Commands
|
|
|
|
```bash
|
|
codex-provider status
|
|
codex-provider sync
|
|
codex-provider sync --keep 5
|
|
codex-provider sync --provider openai
|
|
codex-provider switch apigather
|
|
codex-provider prune-backups --keep 5
|
|
codex-provider restore C:\Users\you\.codex\backups_state\provider-sync\20260319T042708906Z
|
|
```
|
|
|
|
With an explicit Codex home:
|
|
|
|
```bash
|
|
codex-provider status --codex-home C:\Users\you\.codex
|
|
codex-provider sync --codex-home C:\Users\you\.codex
|
|
codex-provider switch openai --codex-home C:\Users\you\.codex
|
|
```
|
|
|
|
## One-Shot Prompt Template
|
|
|
|
Use this prompt in another AI tool if the user wants one-step handling:
|
|
|
|
```text
|
|
I use codex-provider-sync. Please help me fix Codex session visibility under my current provider.
|
|
|
|
Steps:
|
|
1. Run `codex-provider status`.
|
|
2. If my current provider is already correct, run `codex-provider sync`.
|
|
3. If I explicitly tell you to switch provider, run `codex-provider switch <provider-id>` instead.
|
|
4. If SQLite is locked, tell me to close Codex / Codex App / app-server and retry.
|
|
5. If rollout files are skipped because they are locked, tell me which ones were skipped and remind me to rerun sync later.
|
|
6. Summarize the final state of rollout files and SQLite after the command finishes.
|
|
```
|
|
|
|
## User-Facing Summary Style
|
|
|
|
When reporting results back to the user:
|
|
|
|
- state the current provider
|
|
- state whether rollout files and SQLite are aligned
|
|
- mention backup location if a sync or switch was executed
|
|
- call out partial success clearly if locked rollout files were skipped
|