v1.0.0

Detects when a Claude Code session is genuinely close to the limit that ends it, then exports the whole session to disk and continues in a fresh session that reads the parent transcript in full — instead of letting auto-compaction delete most of the conversation and replace it with a summary.

The finding that prompted it

autoCompactWindow in settings.json is silently floored to the model ceiling. A session configured for a 1,000,000-token window was compacted three times at roughly 167,000 tokens, leaving about 830,000 paid-for tokens unused — and nothing in the UI said so.

session_weight.py --explain shows whether this is happening on your machine, with every input named.

What's in it

• A detector on four hook events, plus the session weight on your status line every render
• A context gate: nothing is offered below 62% of the real wall, however many other signals trip
• Five-file session export, and a continuation woken headlessly to read it before you open it
• An installer that is safe to run twice, backs up settings.json, preserves your existing hooks and status line, and reverts cleanly

Compatibility

Pure Python, no dependencies. Reads two documented interfaces rather than patching anything, and prefers evidence from your own transcripts over its own arithmetic — so a release that moves the numbers is self-correcting.

Verified in CI on Ubuntu, macOS and Windows against Python 3.9, 3.11 and 3.13.

Install

git clone https://github.com/IRDcode/claude-code-session-handoff
cd claude-code-session-handoff
python install.py --dry-run     # see every change first
python install.py

The default install does not change how Claude Code manages context. See SECURITY.md for exactly what it reads, writes, and sends (nothing).