codex-rescue 0.1.0a4

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 diagnostic and recovery entry points. The original Codex rollout is read-only; salvage writes only a new handoff under the rescue root.

When a persisted function_call.name contains NUL or another ASCII control character, doctor reports CORRUPTED_TOOL_CALL and keeps only bounded metadata (call id, family, length, codepoints, and a hash) for manual review. The original rollout remains untouched. Rescue does not infer or automatically repair the intended tool name, repair Codex HTTP 400 responses, repair arbitrary malformed arguments, or replay the corrupted call; verify remains fail-closed with REVIEW_REQUIRED.

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 PyPI:

# Recommended global installation via pipx
pipx install codex-rescue

# Or via standard pip
pip install codex-rescue

2. First 5 minutes

Use this sequence with a local Codex installation. It never needs a raw rollout upload:

# 1. Confirm the installation
codex-rescue --version

# 2. Discover recent Codex sessions
codex-rescue sessions

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

# 4. Generate an immutable recovery handoff (the --fork is required)
codex-rescue salvage --latest --fork

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

sessions reads the default Codex home. If it returns no sessions, that is normal on a new machine or before Codex has created a rollout; use --codex-home PATH when Codex runs with a non-default home. doctor and salvage exit with an explanatory “no session discovered” error when there is nothing to inspect. salvage --fork is deliberately required so recovery artifacts are written separately under .codex-rescue/rescues/<rescue-id> and the original rollout is preserved.

verify returns exit code 3 for REVIEW_REQUIRED. That is a conservative result, not a command to replay an uncertain action. Inspect the report and do not automatically repeat unknown side effects.

Troubleshooting

• No sessions found: run codex-rescue sessions --json, check the Codex home path, and confirm that Codex has written at least one rollout. Do not copy or upload an unsanitized session just to make discovery succeed.
• Permission or unsupported-environment errors: record the OS, Python, Codex CLI, and Git versions plus the failing command and exit code. Check that the account running Rescue can read the Codex home and repository; do not modify the original rollout to work around a permission error.
• UNKNOWN or REVIEW_REQUIRED: these statuses are fail-closed. They mean the available evidence cannot prove that continuing is safe. Preserve the original files and report the sanitized diagnostics instead of replaying the action.

When reporting a failure, use the Recovery Report template. Include sanitized JSON, versions, the exact command and exit code, and whether the original rollout stayed unchanged. Never attach raw .jsonl/SQLite files, credentials, private prompts, or unredacted absolute home paths.

3. 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.
• Unknown operational records - unsupported future operational events fail closed and may require review; harmless metadata on known records remains compatible.
• Discovery scope - bounded discovery may miss sessions absent from upstream index state; direct path diagnosis remains useful when the path is known.
• External validation - Alpha 4 remains experimental; no external run on the qualified build, salvage run, or recovery success has been confirmed.

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 (58 passed, 1 expected skip)
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.