claude-rescue
Diagnose and recover corrupted or fragmented Claude Code session files.
Claude Code stores conversations as JSONL files in ~/.claude/projects/. Over time these files can become fragmented (multiple disconnected conversation chains in one file, usually from interrupted sessions or reconnects) or corrupted (entries referencing parents that don't exist). claude-rescue finds these issues and recovers the best chain so you can resume with full context.
Installation
pipx install claude-rescue # recommended
# or
pip install claude-rescue
Commands
diagnose
Scan a project directory and report the health of each session file.
claude-rescue diagnose # current directory (auto-resolved to its Claude project)
claude-rescue diagnose . # same
claude-rescue diagnose ~/work/my-project
claude-rescue diagnose --subagents # also show subagent/compaction files
Example output:
(project root)
Session ID Entries Roots Broken Status Last prompt
---------------------------------------------------------------------------------------------------------------
69e982d2-71f2-447a-a4df-1f90ae590e2d 8682 57 0 ⚠ fragmented please familiarise yourself with...
fbf21b51-e264-4721-adf8-d176907d8404 1824 1 0 ✓ healthy can you add error handling to...
Status meanings:
✓ healthy— single chain, no issues⚠ fragmented— multiple disconnected chains; recoverable✗ corrupted— entries with missing parents; recoverable (dangling entries are dropped)
recover
Recover a single session by ID, keeping the most recently written chain.
claude-rescue recover 69e982d2-71f2-447a-a4df-1f90ae590e2d
Output:
Last prompt: please familiarise yourself with this project
Recovered 57 entries (1769 metadata lines) to:
/home/you/.claude/projects/.../1892d453-aa34-4598-80c0-e214234e0c7d.jsonl
Resume with:
claude --resume 1892d453-aa34-4598-80c0-e214234e0c7d
Options:
--pick— interactively choose which chain to recover instead of auto-selecting--project PATH— specify the project directory if not auto-detected
Running recover twice on the same session without changes prints the existing ID instead of creating a duplicate.
recover-all
Recover every fragmented or corrupted session in a directory.
claude-rescue recover-all # current directory
claude-rescue recover-all ~/work/my-project
claude-rescue recover-all --quiet # suppress per-file resume hints
claude-rescue recover-all --in-place # overwrite originals (backup as .bak)
Compaction files (agent-acompact-*) are always recovered in-place since they have no session ID to resume.
prune-acompact
Delete compaction sidechain files (agent-acompact-*). These are internal transcripts of Claude's context-summarisation runs and are not needed for resuming sessions — the summary itself is stored inline in the main session file.
claude-rescue prune-acompact # current directory
claude-rescue prune-acompact --dry-run # show what would be deleted
On a long-running project this can recover hundreds of MB.
How it works
Claude Code session files are JSONL where each entry has a uuid and optional parentUuid, forming a linked chain. Fragmentation occurs when multiple root entries (entries with no parent) exist in the same file — typically after a reconnect writes a new root instead of continuing from the last entry.
claude-rescue uses a two-pass approach:
- Pass 1 — extract only
uuid/parentUuidvia raw-byte regex (no full JSON parse). Builds the chain tree in ~10 MB of memory regardless of file size. - Pass 2 — stream the file again, writing only entries belonging to the selected chain.
The best chain is selected by highest last-written line number (most recently active chain). Use --pick to override.
Contributing
Issues and pull requests welcome at github.com/Jwrede/claude-rescue.
Metadata
Release files for claude-rescue 0.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| claude_rescue-0.2.1.tar.gz | 10.8 kB | With provenance | Details for claude_rescue-0.2.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| claude_rescue-0.2.1-py3-none-any.whl | Python 3 | none | any | Details for claude_rescue-0.2.1-py3-none-any.whl |
Total release size: 20.7 kB
Release files / claude_rescue-0.2.1.tar.gz
| Download URL | claude_rescue-0.2.1.tar.gz |
|---|---|
| Size | 10.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9b64b17c6ad09516794997c645cedfe2fded07a5e2bc95f6b2977f5ebcd5ffd3
|
|
BLAKE2b-256 checksum How to use checksums |
5b52bce33e6d67d4e7a5a0f9332beccb6e82a63a10b3a25860e92a4e11f38b19
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 2, 2026.
Transparency logRelease files / claude_rescue-0.2.1-py3-none-any.whl
| Download URL | claude_rescue-0.2.1-py3-none-any.whl |
|---|---|
| Size | 9.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3917577871133e0e2e6d0b81c3dd3ae4e14fc52edcb3118ba361d3c57af99ff7
|
|
BLAKE2b-256 checksum How to use checksums |
64c165acbaa2ba3bc5fc9628551aee4dbaae26b6740fce09fb11419d511ff49d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 2, 2026.
Transparency logSecurity for claude-rescue 0.2.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for claude_rescue-0.2.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 2, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.