Codex Session Recovery Skill

English | 简体中文

Recover missing Codex Desktop or Codex CLI conversations from local metadata in minutes. No API-key changes, no cloud scraping, no guesswork: diagnose first, dry-run by default, back up before every repair.

Fastest Recovery

Copy this prompt into Codex:

My Codex sessions disappeared. Use this skill https://github.com/wimi321/codex-session-recovery-skill to recover my Codex sessions.

Codex can use the skill to inspect your local ~/.codex state, explain what it finds, dry-run the safest repair, apply it with backups, and refresh the legacy session index if needed.

Why It Is Easy

• One prompt to start: ask Codex to use the skill and recover the sessions.
• Readable diagnosis: diagnose shows counts, provider hints, stale index state, and the likely next command.
• Safe defaults: repair commands are dry-run unless you add --apply.
• Automatic backups: applied repairs write timestamped backups under ~/.codex/recovery-backups/.
• Credential-safe: the tool never writes auth.json, API keys, OAuth tokens, browser cookies, or provider secrets.

Why This Exists

When Codex history vanishes, the data is often not gone. It may be hidden by local metadata that no longer matches the current app state:

• Provider/profile mismatch, such as old openai sessions under a current local provider like cliproxyapi.
• Reverse provider repairs, where most historical rows suggest one target but the newest Desktop thread shows the app is currently using another provider.
• Sidebar filters scoped to a stale workspace or collapsed group.
• A stale legacy session_index.jsonl.
• Real conversations marked as empty by a drifted has_user_event flag.
• SQLite rows and rollout JSONL metadata drifting out of sync.

This repository packages that recovery knowledge into a Codex skill plus a deterministic Python script that diagnoses first, backs up before repair, and keeps credential material untouched.

What It Can Recover

Symptom	Likely cause	Supported repair
Sidebar is empty after restart	UI state or provider filter	diagnose, then repair-ui-state or repair-provider
Old sessions exist in ~/.codex/sessions but not in Desktop	model_provider mismatch	repair-provider
SQLite shows visible threads but app lists only current sessions	profile/provider mismatch	repair-provider --to auto
SQLite rows exist but visible user thread count is zero	has_user_event drift	repair-user-events, then rebuild-index
Legacy picker misses sessions	stale session_index.jsonl	rebuild-index
Unsure what happened	unknown local state issue	diagnose plus references/incident-patterns.md

This tool is for local Codex state. It does not recover ChatGPT web history, cloud account history, deleted files, or data that no longer exists on disk.

Safety Model

The recovery script is intentionally conservative:

• Never writes ~/.codex/auth.json.
• Does not change API keys, OAuth tokens, browser cookies, or provider secrets.
• Does not upload local session data anywhere.
• Repairs are dry-run by default.
• --apply creates timestamped backups in ~/.codex/recovery-backups/.
• Rollout repairs parse JSON and modify only the first session_meta line after validating the session id.
• Provider repair updates both SQLite and rollout metadata so the fix survives app restarts.
• User-event repair only updates threads.has_user_event after finding first_user_message or real user-authored rollout text.

Manual Quick Start

Clone the repository:

git clone https://github.com/wimi321/codex-session-recovery-skill.git
cd codex-session-recovery-skill

Run a diagnosis:

python3 skills/codex-session-recovery/scripts/codex_session_recovery.py diagnose

If the diagnosis shows old interactive sessions under the wrong provider, run a dry-run provider repair:

python3 skills/codex-session-recovery/scripts/codex_session_recovery.py repair-provider --from openai --to auto

If diagnose says the current provider cannot be resolved from config.toml, check the Latest visible Desktop thread block. A freshly opened blank Desktop thread is often the best provider hint. Use that provider as --to only after a dry-run confirms the direction:

python3 skills/codex-session-recovery/scripts/codex_session_recovery.py repair-provider --from cliproxyapi --to openai --source any --include-empty

Apply only when the dry-run scope is correct:

python3 skills/codex-session-recovery/scripts/codex_session_recovery.py repair-provider --from openai --to auto --apply

If diagnose shows visible rows but zero visible user threads, dry-run and apply the user-event flag repair, then rebuild the legacy index:

python3 skills/codex-session-recovery/scripts/codex_session_recovery.py repair-user-events
python3 skills/codex-session-recovery/scripts/codex_session_recovery.py repair-user-events --apply
python3 skills/codex-session-recovery/scripts/codex_session_recovery.py rebuild-index --apply

Then restart or refresh Codex Desktop and run diagnose again.

Install As A Codex Skill

Link the skill into your local Codex skills directory:

mkdir -p ~/.codex/skills
ln -s "$PWD/skills/codex-session-recovery" ~/.codex/skills/codex-session-recovery

Then ask Codex:

Use $codex-session-recovery to diagnose why my Codex Desktop sessions disappeared.

The skill teaches Codex when to use the script, how to interpret the output, and which safety boundaries must never be crossed.

Command Reference

diagnose

Read-only inspection of local Codex state:

python3 skills/codex-session-recovery/scripts/codex_session_recovery.py diagnose

Reports:

• Codex home path.
• Active profile and resolved provider from config.toml.
• state_5.sqlite thread counts by source/provider/archive state.
• The latest visible Desktop thread provider, which is used as a provider hint when config.toml has no active profile.
• Provider mismatch candidates.
• User-event flag drift candidates, where a real conversation is marked as has_user_event = 0.
• Sidebar state keys.
• session_index.jsonl entry count.
• Suggested next command.

repair-provider

Repairs sessions hidden by provider metadata mismatch:

python3 skills/codex-session-recovery/scripts/codex_session_recovery.py repair-provider --from openai --to auto
python3 skills/codex-session-recovery/scripts/codex_session_recovery.py repair-provider --from openai --to auto --apply

Useful options:

• --to auto resolves the current provider from the active Codex profile.
• If config.toml has no active profile, --to auto falls back to the latest visible Desktop thread provider and prints the source of that inference.
• --source vscode targets interactive Desktop sessions. This is the default.
• --source any broadens the scope after you verify the dry-run output.
• --include-archived includes archived sessions.
• --include-empty includes threads without user events.
• --codex-home <path> targets a non-default Codex home.

repair-user-events

Repairs real conversations that are present in SQLite but marked as empty:

python3 skills/codex-session-recovery/scripts/codex_session_recovery.py repair-user-events
python3 skills/codex-session-recovery/scripts/codex_session_recovery.py repair-user-events --apply

This backs up state_5.sqlite and changes only threads.has_user_event for rows where the script finds either user-authored first_user_message text or user-authored rollout JSONL text. Synthetic <environment_context> messages do not count as user evidence. After applying, run rebuild-index --apply if session_index.jsonl still misses recovered entries.

repair-ui-state

Resets stale sidebar filters and collapsed groups:

python3 skills/codex-session-recovery/scripts/codex_session_recovery.py repair-ui-state
python3 skills/codex-session-recovery/scripts/codex_session_recovery.py repair-ui-state --apply

This backs up .codex-global-state.json, sets the sidebar to all workspaces, uses the recent view, and clears collapsed sidebar groups.

rebuild-index

Regenerates the legacy session_index.jsonl from visible database rows:

python3 skills/codex-session-recovery/scripts/codex_session_recovery.py rebuild-index
python3 skills/codex-session-recovery/scripts/codex_session_recovery.py rebuild-index --apply

How Provider Repair Works

The common failure pattern:

1. ~/.codex/config.toml now points at a custom or local provider.
2. Old interactive sessions still have model_provider = openai.
3. Codex Desktop filters the sidebar to the current provider.
4. Editing only SQLite is not durable, because rollout JSONL metadata can be scanned again on restart.

repair-provider updates both durable locations:

• threads.model_provider in ~/.codex/state_5.sqlite.
• payload.model_provider on the first session_meta line in each matching rollout JSONL file.

Before writing, it confirms the rollout file exists, the first line is session_meta, the session id matches the database row, and the current rollout provider equals the expected --from value.

How User-Event Repair Works

Another real failure mode is state_5.sqlite retaining the old conversation rows and rollout paths while threads.has_user_event is 0. Codex Desktop can then treat the rows as blank threads and hide them from normal history views, even when title, first_user_message, and the rollout JSONL clearly show real conversation content.

repair-user-events looks only for conservative evidence:

1. User-authored threads.first_user_message text, or
2. A rollout JSONL user message with real user-authored text.

It ignores synthetic <environment_context> payloads, backs up the SQLite database, and updates only has_user_event for the matching rows. It does not rewrite rollout files.

Example Output

Codex Session Recovery diagnosis
=======================================
Codex home: /Users/example/.codex
Safety: auth.json/API keys/OAuth tokens are not read or written
Active profile: cliproxyapi
Current provider: cliproxyapi

threads total: 555
visible threads: 554
visible user threads: 554

provider mismatch candidates: 94
rollout provider mismatches: 94

If the dry-run output matches the sessions you want to recover, add --apply.

Lesson From A Reverse Repair

Do not choose the target provider only by counting historical rows. In a later real recovery, a first repair moved old openai rows to cliproxyapi because that was the dominant provider bucket. The sidebar still did not recover. The decisive clue was a newly opened Desktop thread with model_provider = openai; that was the provider the current app was filtering for.

The improved workflow is:

1. Run diagnose --source any --include-empty.
2. Compare the provider counts with the Latest visible Desktop thread hint.
3. Dry-run the direction that moves hidden rows toward the latest Desktop provider.
4. Apply only after every rollout action is safe.
5. Run rebuild-index --apply if a legacy picker still shows stale results.

Project Layout

.
├── README.md
├── README.zh-CN.md
├── CHANGELOG.md
├── CONTRIBUTING.md
├── SECURITY.md
├── .github/workflows/validate.yml
├── skills/codex-session-recovery/
│   ├── SKILL.md
│   ├── agents/openai.yaml
│   ├── references/incident-patterns.md
│   └── scripts/codex_session_recovery.py
└── tests/test_codex_session_recovery.py

Development

Run validation locally:

python3 -m py_compile skills/codex-session-recovery/scripts/codex_session_recovery.py
python3 -m unittest discover -s tests

If you have Codex's skill-creator validator installed:

python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/codex-session-recovery

Roadmap

• Add more incident patterns as the community reports them.
• Add optional JSON output for scripted diagnostics.
• Add restoration guidance for backup directories.
• Expand multilingual documentation as contributors volunteer translations.

Contributing

Issues and pull requests are welcome. Please read CONTRIBUTING.md and SECURITY.md before changing recovery behavior. The safety bar is deliberately high because this project touches local conversation history.

License

MIT. See LICENSE.

Disclaimer

This is a community recovery tool for local Codex metadata. Review dry-run output before applying repairs, and keep backups until you have verified that your history is visible again.