Codex Session Recovery

English | 简体中文

Codex Session Recovery is a small Windows-first tool that repairs and restores local Codex sessions back into the current VS Code session list.

一个专注于本地恢复的轻量工具，用来把 Codex 会话重新修复回当前 VS Code 会话列表。

• Repair missing or hidden local sessions on the current machine
• Restore archived VS Code sessions one by one
• Back up important files before writing changes
• Stay local-first with no cloud services and no telemetry

Download the latest Windows build

Quick Start

Install in editable mode:

cd E:\Dev\Projects\codex-session-recovery
py -3 -m pip install -e .

If the csr command is not available in your shell yet, use the module form during development:

py -3 -m codex_session_recovery.cli version

Read the current state:

csr status --json

Preview a repair without changing files:

csr repair --dry-run --json

Run the repair:

csr repair --json

List archived session candidates:

csr archived list --json

Restore one archived session:

csr archived restore --session YOUR-SESSION-ID --json

Run the desktop UI during development:

py -3 -m codex_session_recovery.desktop_entry

Interface Preview

Main Workspace

One-Click Recovery

Archived Sessions

Safety and Boundaries

• Local-first
• No cloud
• No telemetry
• Backs up files before applying a repair
• Windows-first
• Not a full session manager
• Not guaranteed to support every future Codex internal format without updates

Backups are stored under:

<CODEX_HOME>\.csr-backups\

What It Solves

• Reindex orphan local session files back into session_index.jsonl
• Backfill missing VS Code thread rows into the local state database
• Repair local VS Code session visibility for the active provider
• Optionally patch the VS Code thread list limit
• Restore archived VS Code sessions back into the visible list

What It Does Not Do

• Cloud sync
• Licensing or activation
• Update delivery
• Product management workflows
• Cross-machine migration tooling

CLI Usage

Public CLI surface:

• csr status [--json] [--codex-home PATH]
• csr repair [--dry-run] [--no-patch-limit] [--thread-limit N] [--json] [--codex-home PATH]
• csr archived list [--json] [--codex-home PATH]
• csr archived restore --session ID [--dry-run] [--json] [--codex-home PATH]
• csr version

Development

Run checks:

py -3 -m py_compile src\codex_session_recovery\cli.py src\codex_session_recovery\desktop_entry.py src\codex_session_recovery\desktop_runtime.py
py -3 -m unittest discover -s tests -p "test_*.py"

Build the Windows desktop executable:

powershell -ExecutionPolicy Bypass -File .\scripts\build-exe.ps1

The single-file desktop build is intended to be distributed through GitHub Releases, not committed into the source repository.

License

MIT