Every coding agent session starts with a small lie: "Let me look at the codebase and figure out where we are."
It doesn't know where we are. It doesn't know that yesterday we decided against the rewrite, tried the obvious fix, watched it break two tests, and stopped because we're blocked on a flaky CI job. All of that lived in yesterday's chat. Today's session starts cold — and if the project runs for weeks, you pay this re-explaining tax every single day.
This isn't a fringe complaint. Developers writing about agent workflows keep naming the same failure modes: session-end collapse (everything learned vanishes when the session ends), within-session drift (long threads get compacted and the constraints are the first thing dropped), and cross-tool amnesia (two tools share the same code but none of the memory). People have burned staggering amounts of tokens re-teaching agents things the agent itself discovered a day earlier — and still watched the agent repeat the same mistakes.
Why the obvious fixes fall short
Chat history is the default answer, and it's fragile. Threads get compacted, truncated, or lost when you switch tools or machines. Even when history survives, the signal-to-noise ratio is terrible: the three decisions that matter are buried under forty tool calls.
CLAUDE.md / AGENTS.md files are better, but they solve a different problem. They're for standing rules — how the project is built, what style to follow, what never to touch. Task state is not a standing rule. "Current blocker: the payments webhook returns 200 but does nothing" is true for two days, not forever. Putting it in a rules file means the rules file rots, and research on agent instruction files shows agents will follow a stale instruction file over the actual working code most of the time. That's worse than no note at all.
A plain notes doc gets closest. What killed it for me was trust: three days later I'd open my own notes and not know whether they still described the code in front of me.
The handoff-file approach
So I built a small thing around the one idea that was missing: a handoff should know which code it describes.
A handoff in Handoff Kit is a short, structured note — goal, decisions, checks run, blockers, and one clear next action — captured together with a compact Git snapshot: branch, commit, and changed paths at that moment. You export it as Markdown or JSON, so it can live in the repo, travel with a branch, or be handed to another person or another session.
The second half is a small CLI (capture.py). It creates the Git snapshot, and later it can compare a saved handoff against your current checkout and answer one question: is this handoff CURRENT or STALE? If you're on the same commit with the same changed paths, the note still describes your code. If the branch moved, you know to read the diff before trusting the note. It's not a smart signal. It's a cheap, honest one — and it fixed the trust problem that made me abandon notes.
At the start of a new session, the workflow is: check the handoff, read it (it's short by design), paste or point the agent at it. The agent starts from decisions and dead-ends instead of rediscovering them.
What it deliberately doesn't do
I want to be upfront, because the limitations are part of the design:
- No backend, no accounts, no sync. The web UI is static; drafts live in your browser's local storage.
- No AI inside. Nothing is auto-summarized and there are no model/API calls. You write the handoff yourself. That makes it more work — and means it works with every agent, including future ones, because it's just a file.
- The CLI reads Git metadata only. Not your source contents, not env vars, not chat transcripts.
- No platform integrations. It doesn't capture Claude Code or Cursor chats. It's a format plus a staleness check.
It's an early prototype, MIT licensed, Python 3.9+ for the CLI with nothing to install. There's a live demo if you want to see the format without cloning anything.
What I'd like to learn
I built this for my own workflow, and I'm genuinely unsure which parts generalize. If you use coding agents across multiple sessions:
- Would a CURRENT/STALE signal make you trust a handoff note, or do you just re-read the diff anyway?
- What fields are missing before you'd bother writing one?
- Where should a handoff live — in the repo, or outside it?
Stars on the repo help other people find it, but issues and disagreement will help more. Tell me where this breaks.