explaingit

xdifu/codex-repair

★ 17PythonAudience · developerComplexity · 3/5ActiveLicenseSetup · moderate

TLDR

Python repair toolkit that fixes the SQLite checksum and backfill-timeout crashes Codex Desktop hits after the 0.130 to 0.131 auto-update, while preserving conversation history.

Mindmap

mindmap
  root((codex-repair))
    Inputs
      Codex Desktop SQLite DBs
      Backend binary path
      Codex home dir
    Outputs
      Patched checksums
      DB backups
      Doctor report
    Use Cases
      Recover crashed Codex app
      Diagnose migration drift
      Dry run repair preview
    Tech Stack
      Python
      SQLite
      PowerShell
      WSL

Things people build with this

USE CASE 1

Recover a Codex Desktop install that refuses to start after the 0.130 to 0.131 update

USE CASE 2

Run a read-only doctor scan to confirm whether CRLF vs LF checksum drift is the cause

USE CASE 3

Dry-run the repair against an isolated copy of the DB before applying it

USE CASE 4

Back up and patch state_5.sqlite and logs_2.sqlite without losing chat sessions

Tech stack

PythonSQLitePowerShellWSL

Getting it running

Difficulty · moderate Time to first run · 30min

Needs Python 3.10+ and on Windows you must point the script at the WSL .codex path under /mnt/c.

Apache 2.0, free to use, modify, and redistribute with attribution and patent grant.

In plain English

This repository is a rescue toolkit for users of OpenAI's Codex Desktop app. After a recent auto-update from version 0.130 to 0.131, many users found that the app refused to start, showing dialogs like Codex cannot access its local database, migration 1 was previously applied but has been modified, or timed out waiting for state db backfill after 30s. The toolkit fixes those errors without deleting any conversation history. The README explains what is going wrong. Codex Desktop keeps its data in two SQLite files inside a hidden .codex folder in your home directory. The 0.131 update changed which backend binary the app runs, switching on Windows from a native Windows build to a Linux build that runs under WSL. The new binary has its SQL migration files stored with Linux style line endings, while the old binary used Windows style line endings, and the database stores a checksum of those files to verify nothing has been tampered with. The two checksums no longer match, even though the SQL is the same, so the app refuses to open the database. A second bug then kicks in: a 30 second timeout in the app gives up too quickly while a background job is still loading old chat sessions. The fix is a Python script called codex-repair.py, with a PowerShell wrapper called repair.ps1 for Windows users. The script has two main modes. Doctor mode is read only and inspects the database, the backend binary, and the session files, then reports what it found. Fix mode does the actual repair: it backs up the databases first, verifies the schema, replaces the stored checksums with the ones the new binary expects, and unsticks the background backfill job. Nothing happens unless you pass an apply flag, and an isolated mode runs against a temporary copy of the database for preview. The toolkit takes care to be non destructive. The author says it never touches the conversation history files under .codex/sessions, and it warns against accepting the in-app Repair Codex local data now prompt because that prompt wipes thread metadata. A typical run takes under five minutes including backups. The repo also links to the upstream Codex bug reports it is based on, includes a long root cause writeup in the docs folder, and needs Python 3.10 or newer.

Copy-paste prompts

Prompt 1
Walk me through running codex-repair.py doctor on Windows WSL against my .codex folder
Prompt 2
Explain how codex-repair patches the _sqlx_migrations checksum table in state_5.sqlite
Prompt 3
Write a PowerShell one-liner that calls repair.ps1 with isolated dry-run mode
Prompt 4
Show me where codex-repair backs up the SQLite files before applying the fix
Prompt 5
Adapt codex-repair to also dump the embedded migration SHA-384 hashes from the backend ELF
Open on GitHub → Explain another repo

Generated 2026-05-22 · Model: sonnet-4-6 · Verify against the repo before relying on details.