Your Agent Forgets Nothing — That's the Problem. End Sessions With a Handoff Note

Long sessions with a coding agent often follow a familiar shape. The first hour is sharp. A few hours in, the context is full of dead ends: files you opened and rejected, approaches you tried and abandoned, a refactor you rolled back. The agent still carries all of it in context — and its answers tend to get worse, because the useful state is buried under stale exploration.

The usual fixes are blunt. /clear throws away the state along with the noise. /compact lets the model summarize itself, and the next session starts from that summary — with whatever the summary left out. Starting fresh usually means re-explaining the context by hand.

There is a smaller habit that works better: before you reset, capture the state in a format the next session can execute from.

What a useful handoff note contains

Not a transcript, and not a summary of everything that happened. Five things:

1. Goal state — what you were trying to do, and how far it got.
2. Decisions, with reasons — especially the approaches you rejected, so the next session doesn't retry them.
3. Files touched — what changed, and what's mid-change.
4. Open loops — unverified assumptions, failing tests, questions nobody answered yet.
5. Next action — one concrete step, not a list of possibilities.

Writing this down at the end of a session is quicker than re-deriving it at the start of the next one. And because the note is plain text, it works the same when the "next session" is a different agent, or you next week.

Making it a skill instead of a resolution

Habits that depend on remembering to do them tend to last a week. So I packaged the routine as an installable agent skill: Session Handoff Kit (free, MIT).

It contains three files:

• SKILL.md — the skill itself. When context fills up or a session ends, the agent produces a structured handoff note in the five-part format above.
• context-hygiene-checklist.md — a one-page decision guide: when to /clear, when to /compact, when to start fresh, plus the 2-minute routine to run before any reset.
• handoff-template.md — a fill-in template with per-section guidance, for working without the skill.

Install with the skills CLI:

npx skills add alapha888/session-handoff-kit

or copy SKILL.md into a session-handoff folder in your agent's skills directory. It works with Claude Code, Codex, and Cursor-style skill setups.

The kit is listed on skills.sh, and the source is on GitHub: alapha888/session-handoff-kit. Feedback and issues are welcome there.

You can also read the checklist on its own as a Gist: Context Hygiene Checklist for AI Coding Agents.

The point isn't the tooling — a plain text file works fine. The point is the order of operations: capture state before you reset, in a format the next session can act on without re-asking you everything.