codex-threadkeeper CLI
A utility that brings back Codex threads lost after a provider switch by syncing sessions and SQLite and making backups.
- 106 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The utility edits service files and a SQLite database inside `~/.codex`
- On an incompatible Codex version a state edit may give a wrong result
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/codex-threadkeeperDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The utility edits service files and a SQLite database inside `~/.codex`
- On an incompatible Codex version a state edit may give a wrong result
This is third-party code. Review the repository files before installing.
What it does
After switching `model_provider`, old Codex threads may stay on disk but disappear from the Codex CLI and app: sidebar projects vanish and `codex resume` and the app show different things. The `codex-threadkeeper` utility syncs what the new Codex version depends on: files in `~/.codex/sessions` and `~/.codex/archived_sessions`, the `state_5.sqlite` database (main and fallback), `.codex-global-state.json` and managed backups in `~/.codex/backups_state/threadkeeper`. Run without installing: `npx codex-threadkeeper sync`. After syncing, Codex must be restarted so the app re-reads the index. By default `sync` and `switch` repair the sidebar from current Codex metadata, and the old pinned project list can be restored manually through `pin-project` and `--restore-pinned-projects`. Compatibility is declared with `@openai/codex` 0.142.0.
Who it is for. Codex users who switch model providers and lost sight of session history and sidebar projects.
Good fit when
- After switching `model_provider` the thread history in the Codex app is empty.
- `codex resume` shows some sessions while the app shows others.
- Sidebar projects disappeared after a Codex update.
- A backup of sessions and the database is needed before editing state.
Not a fit when
- The Codex version is much newer than the declared one: the state structure may have changed.
- You just need to move threads between machines rather than repair the index.
- Editing `~/.codex` files is not allowed without a manual backup.
Example request
Use heyroute-ai/codex-threadkeeper to restore Codex session history, then remind me to restart the app.Limitations
The utility edits Codex service files, so it works only on compatible versions: `@openai/codex` 0.142.0 of 23 June 2026 is declared, and for newer ones check support. Node.js 24 or newer is required. Close Codex before running and restart it after syncing. The README has a large block advertising the third-party HeyRoute API service and its speed figures, which is not required for the utility itself. Documentation is in Chinese with an English version. The repository was last updated on 24 July 2026 and uses the MIT licence.
How to disable. Remove the global package with `npm uninstall -g codex-threadkeeper` if you installed it. Backups in `~/.codex/backups_state/threadkeeper` stay and must be removed by hand.
FAQ
What problem does the utility solve?
Old threads stay on disk but are not visible in the Codex CLI and app after switching `model_provider`; the utility aligns the index.
What does it sync?
Session and archive files, the `state_5.sqlite` database, `.codex-global-state.json` and managed backups.
Is installation needed?
No, `npx codex-threadkeeper sync` works. For frequent use there is `npm install -g codex-threadkeeper`.
What to do after syncing?
Restart Codex so the app re-reads the updated history index.
Is HeyRoute required?
No. The utility works with any provider and the HeyRoute block in the README is only promotional.
Discussion
No questions or reviews yet.
Related
CLI toolsA Codex skill for safe local-state maintenance: a report-only default, backup and archive instead of deletion, log and worktree cleanup
A CLI and macOS menu bar app keeping separate Codex profiles for personal and work, each with its own windows, projects and quota.
Codex Relay lets you follow Codex CLI sessions and answer the agent from a phone while the work stays on your computer.
A plugin and MCP tools show where Codex tokens, time, credits and money go, based on local session metadata.
A CLI that shows Codex usage limits and the number of manual resets, and spends one reset after explicit confirmation.
Several desktop Codex copies side by side: each account gets its own icon, sign-in, chats and plugins with no switching.
README in short
The README suggests pasting a ready request into a Codex window so the agent runs the sync itself, and lists the state files the utility touches.