/handoff writes a structured HANDOFF.md at session end. session-start-handoff reads it at the next session start. The session starts with full context instead of reconstructing it from scratch.
Claude Code auto-compresses conversation history when the context window fills up. The compression runs silently and you have no control over it. What the compaction retains: recent messages, file contents, tool outputs. What it discards: the reasoning behind decisions, the exact wording of constraints established early in the session, failed approaches that were discussed but abandoned before touching the filesystem.
By hour two of a session, the model is working from a summary of a summary of the original conversation. It fills gaps with inference. Asking it to recall why you ruled out an approach three hours ago is asking it to reconstruct something it summarized away.
Each Claude Code session starts with an empty conversation context. The model reads CLAUDE.md and any memory files, then waits for input. There is no automatic state transfer between sessions, often avoiding conversation history, in-progress reasoning, and specific edge-cases that were debugged.
The only cross-session persistence is the filesystem. Everything else has to be written down explicitly or it's gone.
git diff and git log show what changed. They don't capture:
- Decisions made in conversation that aren't reflected in code yet
- Approaches tried and discarded before any file was written
- What's half-implemented and in what state
- The constraint that made the obvious solution unworkable
- What the next step is and why
A session with 40 minutes of productive architectural discussion followed by one file edit looks like a one-line commit. The commit message can't hold what the conversation held.
Generates HANDOFF.md by combining git diff --name-only HEAD and git status for accurate file tracking with context extracted from the conversation. Sections:
| Section | Content |
|---|---|
| Goal | What's being built and why |
| Current State | Status, progress %, blocking issues |
| Branch & Commits | Branch name, latest commit hash and subject |
| Files in Flight | Modified files not yet in a stable committed state, with notes on what's incomplete |
| Changed This Session | Every file touched (from git), one-line description each |
| Key Decisions | Architectural and approach decisions from conversation — especially ones not yet visible in code |
| Failed Attempts | What was tried and why it didn't work. This section exists specifically to prevent the next session from repeating the same dead ends |
| Open Questions | Unresolved choices that need input before proceeding |
| Next Step | One specific action, written precisely enough to execute without re-reading the codebase |
Pass --team for a richer format with a For Reviewers section — useful when handing off to a teammate mid-feature.
An agent that activates at session start, reads HANDOFF.md, and presents a sub-20-line brief before the user types anything:
Continuing from your last session (1 day ago).
Goal: Add rate limiting to the API gateway
Status: In Progress — 60%
Branch: feat/rate-limiting
Files in flight:
• src/middleware/rate-limit.ts — Redis integration missing, see Open Questions
• tests/rate-limit.test.ts — unit tests done, integration tests pending
Next step: Wire up Redis in rate-limit.ts using the existing redis-client module in src/lib/
Ready to continue?
Handoffs older than 7 days prompt a staleness check before loading.
git clone https://github.com/thatcatfromspace/claude-handoff-skill
cp -r claude-handoff-skill/skills/handoff ~/.claude/skills/
cp -r claude-handoff-skill/skills/session-start-handoff ~/.claude/skills/
cp claude-handoff-skill/agents/session-start-handoff.md ~/.claude/agents/Restart Claude Code for the skill to be available.
# End of session
/handoff
# End of session, sharing with a teammate
/handoff --team
# Start fresh in the next session
Start fresh, ignore the handoff
On first use, /handoff asks whether to add HANDOFF.md to .gitignore. Personal sessions: yes. Team handoffs where you want the file committed: no.
HANDOFF.md # current handoff (project root)
handoff-archive/ # timestamped previous handoffs
For personal use:
HANDOFF.md
handoff-archive/For team use, commit HANDOFF.md during active development and remove it before merging.
gstack's /context-save stores context in ~/.gstack/sessions/ — scoped to the local machine and designed for Conductor multi-workspace handoffs. This plugin writes HANDOFF.md into the project root: portable, committable, readable by anyone with repo access, and oriented around the end-of-session → start-of-next-session cycle rather than workspace switching.
MIT — Dinesh Veluswamy