I use Claude Code and Codex side by side. Handing off between them was pure pain, so I built a CLI

My workflow is split: Claude Code for some things, Codex CLI for others. Every switch cost me 20 minutes of “wait, where was I” — re-reading transcripts, reconstructing what broke, re-explaining the plan to the new agent.

The transcripts exist locally (~/.claude/projects, ~/.codex/sessions). Nobody was turning them into something the next agent could use. So I built session-handover: it reads both tools’ local transcripts and generates a structured Markdown handover — the goal, what happened, what broke, what’s still open, what the next agent should do.

pip install session-handover
session-handover list          # recent sessions, newest first
session-handover render <id>   # full handover doc

Enter fullscreen mode Exit fullscreen mode

Zero dependencies, stdlib only. Everything stays on your machine — it never uploads your transcripts anywhere.

It’s a small thing, but it changed how I work: sessions became continuable instead of disposable. The handover is honest about failures too — “what broke” is a first-class section, because the next agent needs to know what didn’t work more than what did.

Repo: https://github.com/hahahahahahahahah6/session-handover

MIT licensed. If you multi-tool like I do, try it and tell me what’s missing from the handover format.

Update (v0.2): audit what /compact drops

There’s a failure mode nobody audits. /compact silently drops things the session established — claude-code#67500 is literally “compaction dropped my project rules”, claudefa.st keeps a “What Survives /compact” survival table, and mikepurvis asked on HN for a formal framework of what survives compaction. The summary that replaces your context is lossy, and nothing checks the diff.

So v0.2 adds session-handover audit-compact:

1. Boundary detection — finds compaction events in the transcript (Claude Code’s summary entries and the “continued from a previous conversation” preamble; Codex best-effort).
2. Durable-item extraction — from the turns before the boundary, pulls out rules (“never push without asking”), TODOs, decisions, preferences, each citing its source turn. Heuristic and conservative, no LLM.
3. Survival check — matches each item against the replacement summary text. Matching is token overlap (≥50% of distinctive tokens), not semantic; misses are reported as DROPPED with the original sentence as a one-line “suggested restore” the next agent can paste back.
4. Report — terminal summary plus --out AUDIT.md; exit 0 always, or --fail-on-drop for CI/hook use. No detectable boundary prints a clear message and exits 0 instead of erroring.

Honest as ever: extraction misses subtly-phrased rules, token overlap is not meaning (a reworded-but-surviving rule gets flagged), and compaction markers are undocumented — a missed boundary is a silent miss, not a crash.

29 tests pass, stdlib-only as before.

If you also bounce between agents: what does your handover ritual look like? I’m curious what I missed.

Update (v0.3): the hook that writes the handover before /compact

v0.2 audits what compaction dropped. v0.3 prevents the loss. The pattern is everywhere once you look: Silta’s hand-written handoff+compaction process, Recall’s pre-compact hook, the plan-mode Ask HN thread where people manually split PLAN_*.md files. When /compact fires, the session’s durable state needs a structured handover written before the summary replaces context — and today that step is manual.

One command:

session-handover hook-install precompact

Enter fullscreen mode Exit fullscreen mode

On every /compact, the hook generates the standard handover from the transcript as it currently stands, then appends a “Durable items the next session must preserve” checklist — rules, TODOs, decisions, preferences, each citing its source turn — and writes it to ~/.cache/session-handover/precompact/HANDOVER.<session>.md. Even if the auto-summary is lossy, the restore checklist is on disk.

Fail-open by design: any failure prints a stderr note and exits 0. It never blocks compaction. Honest as ever: the hook protocol is undocumented and can drift (then the hook becomes a silent no-op), and the checklist inherits the audit’s heuristic extraction limits — a safety net, not a guarantee.

41 tests pass, stdlib-only as before.

Update (v0.3.1): two real-world fixes

An independent review caught two bugs that only show up outside the test suite.

First: hook-install registered the PreCompact hook as python3 <shim>, which breaks under pipx, venv, uv, or Homebrew Python — the hook silently never runs. It now registers the absolute path of the running interpreter (sys.executable), and the regression test installs into a real venv and executes the registered command end to end.

Second: find_boundaries treated any {"type": "summary"} line as a compaction, but that’s also the shape of a plain session title. It now only counts real compaction markers — a system entry of subtype compact_boundary or a user message flagged isCompactSummary. The “continued from a previous conversation” preamble path is untouched.

45 tests pass (41 existing + 4 new), stdlib-only as before.