Codex history recovery

Codex History Recovery

Use this skill to recover Codex Desktop task lists without touching conversation rollout content. Treat the JSONL rollout files as the source of truth and repair only metadata, catalogs, and project assignment state.

Safety Rules

• Back up every database or JSON state file before writing.
• Never delete session JSONL files, archived session JSONL files, repositories, worktrees, or user outputs.
• Prefer dry-run first. Run the bundled script with --apply only after checking the proposed changes.
• If the app is open, expect .codex-global-state.json to be overwritten by the desktop process. For project assignment repairs, write the final global-state update last and ask the user to fully quit/reopen Codex.
• Do not use broad destructive cleanup of WebView, Local Storage, or caches unless the user explicitly asks and login state risk is acceptable.

Quick Workflow

1. Inspect the current state:

python3 "$CODEX_HOME/skills/codex-history-recovery/scripts/recover_codex_history.py" inspect

2. If the script reports missing visible threads, CODEX_HOME mismatch, provider mismatch, or missing project assignments, run a dry-run repair:

python3 "$CODEX_HOME/skills/codex-history-recovery/scripts/recover_codex_history.py" repair --dry-run

3. Apply the repair:

python3 "$CODEX_HOME/skills/codex-history-recovery/scripts/recover_codex_history.py" repair --apply

4. Fully quit ChatGPT/Codex Desktop and reopen it. If project grouping still looks wrong, run the repair again after the app is closed.

What The Script Repairs

• Synchronize or compare state databases:
  • Runtime state is often under /root/.codex/sqlite/state_5.sqlite.
  • Windows user state is often under /mnt/c/Users/<user>/.codex/state_5.sqlite.
  • App catalog is often under /mnt/c/Users/<user>/.codex/sqlite/codex-dev.db.
• Create compatibility symlinks when the runtime DB expects rollout paths under /root/.codex/sqlite but the real rollout tree lives under the Windows $CODEX_HOME.
• Normalize WSL/Windows paths so saved project roots match thread cwd values.
• Rebuild local_thread_catalog from state DB rows.
• Mark unarchived top-level local tasks with the visible local model_provider value when older metadata makes the current desktop list filter them out.
• Restore project assignments in .codex-global-state.json from saved local-projects and thread cwd values.
• Remove temporary mass pins while preserving existing pinned threads when possible.

Manual Checks

Use these checks when the script cannot decide safely:

python3 - <<'PY'
import sqlite3
for p in ['/root/.codex/sqlite/state_5.sqlite', '/mnt/c/Users/tuml/.codex/state_5.sqlite']:
    con = sqlite3.connect(p)
    cur = con.cursor()
    print(p, cur.execute('pragma integrity_check').fetchone()[0])
    print(cur.execute('select model_provider, thread_source, archived, count(*) from threads group by 1,2,3').fetchall())
PY

python3 - <<'PY'
import json
p = '/mnt/c/Users/tuml/.codex/.codex-global-state.json'
data = json.load(open(p, encoding='utf-8'))['electron-persisted-atom-state']
print(data.get('local-projects', {}))
print(data.get('thread-project-assignments', {}))
print(data.get('pinned-thread-ids', []))
PY

Project Assignment Heuristic

Assign a thread to a local saved project when its normalized cwd is equal to a saved project root or lies under one of that project's rootPaths. Use the saved project's stable id from .codex-global-state.json, not a guessed id.

Do not assign projectless Codex output directories such as /mnt/c/Users/<user>/Documents/Codex/YYYY-MM-DD/... to arbitrary repos unless the user explicitly says they belong to a saved project.

Incident Reference

For the 2026-07-20 recovery that motivated this skill, read references/incident-2026-07-20.md when exact field names, symptoms, or validation output are needed.