Every AI coding session starts the same way. The agent reads the README, the config, the files it touched yesterday, the tests, and then it is finally ready to do the thing you asked. On a mid-size repo that re-orientation runs 20k to 60k tokens before any new work happens. Two sessions a day, five days a week, and you are paying frontier-model prices for the agent to remember what it already knew.
We measured it on our own repos and it was worse than we expected. So we built a fix and open-sourced it.
The idea #
Context Handoff Bundle is a small Python package that saves a session's working state as a durable bundle: the findings, the open questions, the decisions, and evidence anchors pointing at the exact files and commits those findings came from. The next session loads the bundle instead of re-reading the repo.
One real load from our own use:
[tokens] resume: ~640 | re-deriving from source (6 files): ~23.0k | saved: ~97% (chars/4 estimate)
About 640 tokens to resume instead of about 23,000 to rebuild. The estimate is chars divided by four, printed on every load, so you can judge it against your own repo rather than trust ours.
The part that matters: it knows when it is stale #
A saved summary is only useful if you can trust it. The bundle checks its own evidence anchors against the live repo on load. If a file a finding depended on changed, that finding is flagged. If most anchors drifted, the recommendations are flagged. If nothing moved, it says so and gets out of the way.
We shipped three releases in two days, each one fixing a failure we hit on a real repo:
- 0.3.0 stopped treating every anchor as a file path. A commit hash is verified as a commit, a URL as a URL, so healthy bundles stopped crying wolf.
- 0.3.1 fixed renames. A plain
git mvused to mark every anchor gone and escalate the whole bundle to HIGH. Someone on Reddit asked about it within an hour of launch, and the fix was live that afternoon. - 0.4.0 made anchors per-finding. A finding now carries only the anchors its text actually cites. Edit one file and the one finding that depended on it gets flagged at MEDIUM. Under 0.3.1 all of them flagged at HIGH. Findings that cite nothing are reported as unanchored, so an uncheckable claim never passes as a verified one.
What it is not #
It is not memory magic and it is not a vector database. It is a structured file in your repo, with a schema, a validator, and a confidence score. Zero runtime dependencies. Python 3.10 or newer. MIT licensed. There are Claude Code slash commands in the box (/handoff-save, /handoff-load) and a plain CLI for everything else.
Try it #
pip install context-handoff-bundle
Source and docs: github.com/ucsandman/context-handoff-bundle
If your agent is spending its first ten minutes every morning rereading your codebase, this is the cheapest fix we know of.