# Restore Codex Conversations

> Diagnose, back up, restore, and verify local Codex Desktop conversations whose rollout JSONL files still exist but disappear from the sidebar or project grouping after an account, model-provider, authentication, or client-version change. Use when Codex must inspect or repair state_5.sqlite, session_index.jsonl, rollout session_meta, .codex-global-state.json project mappings, or reuse the bundled recovery script. Do not use for cloud-chat export/import or for remapping project files between disks without an explicit path-migration request.

- Skill: `laywr/restore-codex-conversations` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add laywr/restore-codex-conversations`
- Raw SKILL.md: https://api.skillmd.com/api/skills/laywr/restore-codex-conversations/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: Laywr (https://skillmd.com/u/laywr)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/laywr/restore-codex-conversations

---


# Restore Codex Conversations

Restore local conversation visibility with a backup-first, evidence-driven workflow. Treat database rows, rollout metadata, the session index, and project mappings as one consistency set.

## Safety rules

1. Limit writes to the current computer's active Codex home, normally `%USERPROFILE%\.codex` or `$CODEX_HOME`.
2. Treat attached old system or project disks as read-only unless the user explicitly authorizes writes or path remapping on those disks.
3. Preserve archived threads, subagent threads, original timestamps, cwd values, sandbox boundaries, and rollout history unless a verified compatibility requirement says otherwise.
4. Back up the SQLite database consistently, the global state, the session index, and every target rollout before mutation.
5. Derive `model_provider` and `cli_version` from a currently visible official-account main thread. Never copy provider/version constants from examples.
6. Request the required filesystem approval before writing outside the workspace. Do not work around a denied write.
7. Never delete Electron Local Storage or Session Storage as a first-line recovery step.

## Workflow

### 1. Establish scope

- Resolve the active Codex home and verify that `state_5.sqlite`, `.codex-global-state.json`, `session_index.jsonl`, and `sessions/` belong to the current installation.
- If the user requested diagnosis or explanation only, remain read-only and report the consistency gaps. Execute repairs only when the request authorizes restoration.
- If old disks are attached, distinguish the current Codex home from historical copies before any mutation.

### 2. Inspect before changing

- Read [references/restore-project-conversations.md](references/restore-project-conversations.md) completely before performing a migration. For a read-only diagnosis, read the sections covering scope, template selection, target selection, and validation.
- Locate a usable `sqlite3` executable from `--sqlite`, `$SQLITE3_PATH`, or PATH rather than assuming one installation path.
- Count main, archived, and subagent threads separately.
- Verify every selected `rollout_path` exists on the current computer and begins with `{`, not a UTF-8 BOM.
- Compare database main-thread IDs with `session_index.jsonl`, `thread-writable-roots`, and `thread-project-assignments`.
- Select a current visible official main thread as the provider/version template.

### 3. Choose the repair path

Prefer [scripts/restore_codex_conversations.js](scripts/restore_codex_conversations.js) when the active schema matches the reference and the user requested restoration. Run it without `--apply` first; the default mode is a read-only preflight. Review the selected template and targets, then rerun with `--apply` only after the repair scope is confirmed.

Use the manual procedure in the reference when:

- the schema differs from the script's expected `threads` columns;
- the target is a small, explicitly named subset;
- rollout metadata is malformed beyond the first line;
- project-path migration is also requested;
- the script's preflight validation fails.

Do not run the script if no currently visible official main thread exists; first ask the user to create one so the compatibility template is observable.

### 4. Execute narrowly

- Migrate unarchived main threads whose provider is incompatible with the current template.
- Exclude guardian, reviewer, and other subagent rows.
- Keep `source` semantics, cwd, archived state, timestamps, and sandbox policy unless the current schema requires a documented change.
- Update only rollout line 1 when repairing `session_meta`; preserve the remaining bytes.
- Write JSON and JSONL as UTF-8 without BOM.
- Add missing session-index rows without replacing existing human-friendly thread names.
- Add or repair `local-projects`, `thread-writable-roots`, and `thread-project-assignments` using exact or longest-root matching.
- Never mechanically replace old drive letters with attached-disk drive letters.

### 5. Verify at every layer

- Run `PRAGMA integrity_check`; use `wal_checkpoint(TRUNCATE)` after the client exits or `PASSIVE` while it remains open.
- Recount official-compatible, archived, and subagent rows.
- Parse each changed rollout first line and confirm the first byte is `7B`.
- Parse every session-index line and the entire global-state JSON.
- Confirm backup and manifest files exist.
- If Codex thread tools are available, search for and read an old thread. Do not send it a new task merely to test restoration.
- Fully restart Codex Desktop, then verify the old conversation appears under its project and opens with historical turns.

## Bundled resources

- `references/restore-project-conversations.md`: detailed schema notes, SQL examples, backup requirements, project mappings, failure modes, and manual checklist.
- `scripts/restore_codex_conversations.js`: deterministic migration used successfully on the source machine. It resolves the active Codex home and `sqlite3` portably, defaults to a read-only preflight, dynamically chooses a current-account template, creates backups on `--apply`, updates compatibility metadata and mappings, and performs integrity checks.

Treat the script as a migration tool, not a Codex runtime dependency. Review its default paths and arguments on every new machine or client schema.