← All notes
context-bridge · 1 min read

Vendor session formats break silently

The worst bug in context-bridge was not in my code. Every handoff reported success and carried an empty delta.

Claude Code, Codex and Grok keep their sessions in internal files. Nobody documents them and nobody owes you stability. Fair enough, they are internal files, not a public API. But context-bridge reads them anyway. Then a point release renames one field and nothing looks broken: the binary still runs, auth still works, and bridge handoff reports success. That is the failure mode I hate most, because everything looks alive from the outside.

So bridge doctor got a check nobody asked for. It does not check whether Claude is installed or Codex is logged in. It opens each vendor's session files and confirms that this version of the bridge can still parse them. It exists because this failure stays invisible until you notice that a week of handoffs carried nothing.

What I keep from it: when you build on another product's internal files, "installed and logged in" tells you nothing. Test the data you depend on, not the binary that writes it.