Repair Codex History

中文说明

A Codex skill and repair script for diagnosing Codex Desktop/App history sessions that still exist on disk but no longer appear in the sidebar, project history, or search after switching accounts, API keys, API vendors, model providers, or Codex versions.

This project was created from a real recovery case where old sessions were still present under ~/.codex/sessions, but Codex only showed newer conversations. The root cause was stale rollout session_meta values such as an old model_provider and missing thread_source.

What It Fixes

This tool is intended for cases like:

• Old Codex conversations disappeared from the Desktop/App sidebar.
• Project conversations appear under generic "Conversations" instead of their original projects.
• A session can be read by thread ID, but does not appear in history lists.
• You switched from one account/API/vendor/provider to another and older sessions became hidden.
• Editing state_*.sqlite seemed to work briefly, but Codex reverted the changes after restart.

It works by inspecting and, when explicitly requested, repairing:

• ~/.codex/sessions/**/rollout-*.jsonl
• ~/.codex/state_*.sqlite
• ~/.codex/.codex-global-state.json
• ~/.codex/session_index.jsonl

Important Limitations

This is not a universal recovery tool.

It only helps when the original rollout session files still exist:

~/.codex/sessions/**/rollout-*.jsonl

It cannot recover conversations if the source files were deleted.

It is primarily aimed at Codex Desktop/App history and project grouping. Codex CLI users may still benefit from the inspection logic, but CLI history behavior is not the same as the Desktop/App sidebar.

Support Matrix

Environment	Status	Notes
macOS + Codex Desktop/App	Tested	Original recovery environment.
Linux + Codex Desktop/App	Likely	Should work if paths and sqlite3 are available.
Windows	Experimental	Not fully tested. Path handling and SQLite CLI availability may need fixes.
Codex CLI only	Limited	Useful for inspecting rollout metadata, but project/sidebar repair is Desktop/App focused.
Deleted ~/.codex/sessions files	Not supported	There is no source history left for this tool to repair.

Requirements

• Node.js
• sqlite3 command-line tool
• Existing Codex home directory, usually ~/.codex

Check:

node --version
sqlite3 --version

Install As A Codex Skill

Copy this folder into your Codex skills directory:

mkdir -p ~/.codex/skills
cp -R repair-codex-history ~/.codex/skills/repair-codex-history

Then restart Codex.

Use The Script Directly

Always start with a dry run:

node ~/.codex/skills/repair-codex-history/scripts/repair_codex_history.js --dry-run

The dry run prints:

• detected Codex home
• selected state_*.sqlite
• candidate providers
• rollout metadata distribution
• proposed rollout changes
• project roots
• skipped files

If the output looks correct, quit Codex Desktop/App completely, then apply:

node ~/.codex/skills/repair-codex-history/scripts/repair_codex_history.js --apply

If you already know the provider you want old sessions normalized to:

node ~/.codex/skills/repair-codex-history/scripts/repair_codex_history.js --apply --target-provider your-provider-name

For a non-default Codex home:

node ~/.codex/skills/repair-codex-history/scripts/repair_codex_history.js --dry-run --codex-home /path/to/.codex

How To Choose --target-provider

The target provider should usually match the provider used by sessions that currently show correctly.

Examples:

• You used API/vendor A before, then switched to API/vendor B.
• New sessions under B show correctly.
• Old sessions under A are hidden.
• The target provider should be B's model_provider value.

The script tries to infer this automatically from recent visible user sessions. If it cannot infer a provider, it stops and asks you to specify --target-provider.

Do not copy someone else's provider name blindly. Inspect your dry-run output first.

Safety

By default, the script is read-only:

node scripts/repair_codex_history.js --dry-run

The script only writes when --apply is provided.

On apply, it creates a backup directory under ~/.codex, for example:

~/.codex/.repair-backups-YYYYMMDDHHMMSS-history-skill

Backups include:

• the selected SQLite database
• .codex-global-state.json
• session_index.jsonl
• every rollout file changed by the repair
• repair-manifest.json

Do not delete ~/.codex/sessions when troubleshooting.

What The Repair Changes

The script repairs source metadata first:

rollout-*.jsonl -> first session_meta line

It normalizes user sessions to:

{
  "source": "vscode",
  "thread_source": "user",
  "model_provider": "target-provider"
}

It preserves cwd, because cwd is what keeps project conversations associated with their original project.

After repairing rollout metadata, it syncs generated state:

• state_*.sqlite
• .codex-global-state.json
• session_index.jsonl

This matters because Codex may rebuild SQLite from rollout files on startup. If you only edit SQLite, the repair can be overwritten.

Typical Recovery Flow

1. Confirm source files still exist:

find ~/.codex/sessions -name 'rollout-*.jsonl' | head

2. Run dry-run:

node scripts/repair_codex_history.js --dry-run

3. Review:

• providerCandidates
• rolloutMetaDistribution
• proposedRolloutChanges
• projectRootList
• skippedRollouts

4. Quit Codex Desktop/App.

5. Apply:

node scripts/repair_codex_history.js --apply

6. Reopen Codex and check sidebar/project history.

Manual Inspection Commands

Show thread metadata distribution:

sqlite3 -header -column "$HOME/.codex/state_5.sqlite" \
"SELECT model_provider, thread_source, archived, has_user_event, COUNT(*) n
 FROM threads
 GROUP BY model_provider, thread_source, archived, has_user_event
 ORDER BY archived ASC, has_user_event DESC, n DESC;"

Inspect a rollout file's first metadata line:

head -n 1 "$HOME/.codex/sessions/path/to/rollout-file.jsonl"

Publishing Notes

This skill intentionally avoids claiming full compatibility with every Codex version or platform. Codex's internal history schema may change. Treat this as a cautious repair utility for a known class of metadata/indexing problems.

When reporting issues, include:

• operating system
• Codex surface: Desktop/App or CLI
• Codex version if known
• dry-run output
• whether rollout files still exist
• whether state_*.sqlite contains the missing thread IDs