The work was done. Four hours of it. A migration across a dozen files, two PRs, a deploy, and a pile of small decisions that only made sense if you had been there for all four hours.
Then I hit /clear.
The next session opened clean and confident and completely ignorant. It re-read files it had already fixed. It suggested an approach we had tried and abandoned in hour two, for reasons that were obvious at the time and invisible now. It asked me to confirm things I had confirmed twice already.
I spent the next hour re-explaining my own project to a tool that had helped me build it.
Context Doesn't Persist, and Nothing Warns You
This is the part that catches people. A long Claude Code session accumulates an enormous amount of working knowledge: which files matter, what the failure mode was, why the obvious fix doesn't work here, what you already ruled out. None of that is written down anywhere. It lives in the context window, and the context window is temporary.
When it goes, it goes silently. There's no "you are about to discard four hours of reasoning" prompt. You clear, the session resets, and the loss only shows up later as re-derived work.
The usual workarounds don't hold up:
- Scrollback. The information is technically there, buried across hundreds of messages. Finding it costs more than re-deriving it.
- A giant CLAUDE.md. Good for standing facts like architecture and conventions. Wrong shape for "here is where we are today and what's half-finished."
- Remembering it yourself. You will remember what changed. You will not remember why you rejected the obvious approach, which is the expensive part.
- Asking for a summary before clearing. Closer, but you get chat-shaped prose that is confidently wrong about anything that changed out of band, because it summarizes the conversation rather than checking reality.
What I actually needed was a document. Written before the clear, structured for a reader who wasn't there, and verified against the repo rather than against the transcript.
The Fix: A Skill That Writes the Handoff
Claude Code skills are folders of instructions that load when they're relevant. So I wrote one. Say "write a handoff" and it produces a single markdown file capturing what changed, what's true now, what's left, and what would bite someone who didn't live through the session.
Install it with one command:
curl -fsSL https://ookay.dev/skills/session-handoff/install.sh | bash
That drops the skill into ~/.claude/skills/session-handoff/, so it's available in every project. For a single repo instead, install it project-level:
curl -fsSL https://ookay.dev/skills/session-handoff/install.sh | bash -s -- --project
Restart Claude Code and say "write a handoff" before your next /clear.
If you would rather not pipe a script from the internet into your shell — a reasonable instinct — read it first. It's twenty lines and all it does is curl three files into a directory. You can also just create ~/.claude/skills/session-handoff/ by hand and drop in SKILL.md, assets/handoff-template.md, and scripts/collect-context.sh.
What It Actually Produces
The output is one file, saved somewhere discoverable like docs/handoff-<topic>-<date>.md. It has a fixed shape:
- Changelog — what changed, grouped by area, with real PR numbers and file paths.
- Current state (verified) — what is true now: merged, deployed, passing, and how each claim was confirmed.
- Open items, split into things only a human can do (add a secret, click merge) and work the next agent can pick up.
- Gotchas and non-obvious context — why an approach was chosen, what looks wrong but isn't, what was deliberately not done.
- How to continue — exact commands and entry points.
- Honest limitations — what's incomplete or assumed, so nobody over-trusts the document.
Two of those sections do most of the work.
Gotchas is the highest-value part, because it's the only section a fresh agent cannot reconstruct from the diff. A diff shows you that a retry wrapper was added. It does not tell you the retry wrapper exists because the upstream API returns 200 with an empty body under load, and that the obvious fix — checking the status code — silently does nothing. That costs an hour to rediscover and one sentence to write down.
Deliberately not done is the close second. Without it, the next session cheerfully re-attempts the thing you already proved doesn't work.
The Part That Makes It Trustworthy
The rule that matters most: verify against reality, not against the conversation.
A summary generated from the transcript will tell you a PR is open when you merged it from the GitHub UI twenty minutes ago. It will describe a file as it was when it was read, not as it is now. Chat history is a record of what was believed, not what is true.
So the skill ships with scripts/collect-context.sh, which dumps actual current state before anything gets written — branch, uncommitted changes, recent commits, diff stat against a base ref, and open and recently merged PRs if gh is available:
bash ~/.claude/skills/session-handoff/scripts/collect-context.sh [since-ref]
Every "done" claim in the handoff gets checked against that output rather than against memory. The document says a PR is merged because gh reports it merged, not because merging it was discussed.
When to Use It
The obvious moment is right before /clear. The less obvious ones matter more:
- End of a work session, so tomorrow-you starts from a document instead of scrollback.
- Handing off to another agent or another person.
- After any large multi-step task, even mid-session — the reasoning is freshest immediately after the work, and cheapest to capture then.
There's a related habit worth building: if a session turns up something durable — architecture, where credentials live, a gotcha that recurs — put it in memory or CLAUDE.md too. The handoff is point-in-time; memory is standing. Different jobs, and the skill will nudge you on the distinction.
Honest Limitations
It writes a document; it doesn't verify your work. If your session's conclusions were wrong, you get a well-organized record of wrong conclusions.
It's also only as good as what it can check. The verification step covers git and GitHub state. It can't confirm that your deploy actually serves traffic or that a test suite is meaningful rather than merely green — those still get written as claims, which is why "Honest limitations" is a required section rather than a nicety.
And it costs a few minutes at the end of a session, at exactly the moment you feel finished and want to stop. That's the real adoption barrier. The trade is a few minutes now against an hour of re-derivation later, which is a good trade roughly every time, and one that's very easy to skip.
I've been running it for a while now. The handoff files have quietly turned into the most useful documentation in a couple of my repos — not because they're well written, but because they're the only place the reasoning got recorded before it evaporated.
If you want the other half of this — checking what a session actually did against what it was asked to do — I wrote about the ticket-review agent separately.