codex-rescue 0.1.0a1

Overview

When OpenAI Codex CLI can't resume safely, Rescue tells you what actually happened and gets you back to work.

Codex Rescue is a local-first fsck and crash-recovery tool for OpenAI Codex sessions. It diagnoses interrupted or damaged sessions, verifies repository working tree state, and reconstructs a bounded evidence-backed continuation without modifying the original Codex rollout.

[!WARNING] Codex Rescue is experimental alpha software. It is an evidence-gathering release designed to collect real failure cases. See Alpha Limitations below.

Core Commands

Rescue provides four narrow, read-only diagnostic and recovery entry points:

Confidence Model

Rescue reconstructs facts with explicit, uncompromised confidence levels. Model prose alone is never accepted as source of truth.

[!NOTE] Safety Invariants:

1. Source rollouts are immutable (doctor, salvage, and verify never write to the original .jsonl file).
2. No automatic replay — an action whose execution status is UNKNOWN is never automatically re-executed.

Quick Start

1. Installation

Install directly from the GitHub release tag:

# Recommended global installation via pipx
pipx install git+https://github.com/shleder/codex-rescue.git@v0.1.0-alpha

# Or via standard pip
pip install git+https://github.com/shleder/codex-rescue.git@v0.1.0-alpha

2. Workflow Example

# 1. Discover recent Codex sessions
codex-rescue sessions

# 2. Diagnose the latest session
codex-rescue doctor --latest

# 3. Generate an immutable recovery handoff
codex-rescue salvage --latest --fork

# 4. Verify repository state before continuing
codex-rescue verify <rescue-id>

Sample Output

$ codex-rescue doctor --latest

Doctor: UNFINISHED_TOOL_CALL
Findings: UNFINISHED_TOOL_CALL
Repository: /path/to/repo (HEAD a6cfe48)

$ codex-rescue salvage --latest --fork

Salvage: 8f8f4e822c9ce353ed584c5f
Original session untouched: yes
Rescue directory: .codex-rescue/rescues/8f8f4e822c9ce353ed584c5f

$ codex-rescue verify 8f8f4e822c9ce353ed584c5f

Verify: REVIEW_REQUIRED
Review: unfinished action requires inspection before replay
Review: handoff contains load-bearing unknowns

Proven Compatibility & Evidence

Alpha Limitations

[!IMPORTANT] The following limitations are documented honestly. Do not claim recovery guarantees that have not been validated.

• Compaction recovery — broad real compaction-related recovery is not yet validated; only synthetic fixtures exist.
• Interactive continuation — automatic fresh continuation depends on terminal/TTY environment (Windows ConPTY limitations noted).
• Previous versions — validation is focused on Codex CLI 0.147.0; earlier versions are smoke-tested or observed.
• Side-effect replay — Rescue does not automatically replay unknown side effects; it reports them as REVIEW_REQUIRED.

Privacy & Security

• 100% Local-First — zero telemetry, zero analytics, zero network uploads, zero cloud dependencies.
• No private DB mutation — Rescue never modifies state_*.sqlite or internal Codex databases.
• Secret Redaction — built-in secret redaction automatically filters common API key patterns (sk-*, ghp_*, AKIA*, Bearer tokens).
• Sanitization Notice — Codex rollouts can contain secrets; sanitize all session files before attaching to public issues.

Development & Verification

# Clone the repository
git clone https://github.com/shleder/codex-rescue.git
cd codex-rescue

# Install in editable mode
pip install -e .

# Run full unit test suite (43 passed, 1 skipped)
python -m unittest discover -s tests -v

# Run synthetic fixture harness (5/5 PASS)
python -m codex_rescue.harness fixtures --output .validation-output/test

# Run deterministic alpha demo
python scripts/demo_alpha.py

Submit a Recovery Report

The primary goal of this public alpha is collecting real broken Codex sessions to expand our sanitized regression corpus.

Open a Recovery Report →

[!CAUTION] Do NOT upload raw rollout files containing secrets or credentials. Always sanitize session data before attaching.

License

Distributed under the MIT License. Copyright (c) 2026 shleder.