Never lose context between AI coding sessions.
Two skills for Claude Code that capture decisions, failed approaches, measurements, and next steps — so your next session picks up exactly where you left off. Stop wasting 20-40% of each session rediscovering what was already tried.
git clone https://github.com/REMvisual/claude-handoff.git
cp -r claude-handoff/skills/handoff ~/.claude/skills/
cp -r claude-handoff/skills/handoffplan ~/.claude/skills/Verify: type /handoff in Claude Code — it should appear in autocomplete.
/handoff # Capture session context — next session explores
/handoffplan # Capture context + write a plan — next session executes
No arguments needed. The skill mines your full conversation, gathers git state, validates the output, and gives you a ready-to-paste resume prompt:
Read `plans/handoffs/HANDOFF_fix-auth-bug_2026-03-19.md` (seq 2, PROJ-abc1)
and continue from "Where We're Going".
Paste that into a fresh Claude Code session. It picks up the chain and starts working.
Every handoff captures a structured snapshot of your session:
┌─────────────────────────────────────────────────────┐
│ HANDOFF_fix-auth-bug_2026-03-19.md │
├─────────────────────────────────────────────────────┤
│ The Goal — what we're solving and why │
│ Where We Are — 15-25 bullets of current state│
│ What We Tried — every approach, chronological │
│ Key Decisions — what was chosen AND rejected │
│ Evidence & Data — real numbers, not summaries │
│ User Feedback — preferences, corrections, tone│
│ Where We're Going — ordered next steps │
│ Quick Start — exact commands for next session│
└─────────────────────────────────────────────────────┘
"What We Tried" is the most valuable section. Failed approaches are the most expensive thing to rediscover. This section captures every attempt — what was tried, what happened, why it was kept or abandoned — so the next session never repeats work.
Both capture your session. The difference is what the next session does:
/handoff |
/handoffplan |
|
|---|---|---|
| When to use | Pausing mid-work | Done with research, ready to build |
| What it writes | Handoff file | Handoff + phased plan + tracked tasks |
| Next session | Reads handoff, onboards, explores | Reads plan, claims Phase 1, starts coding |
| Paste prompt | "Continue from Where We're Going" | "Execute the plan starting at Phase 1" |
/handoffplan creates beads (or tasks in your tracker) with dependency chains between phases, anti-goals from failed approaches, rollback strategies, and success criteria tied to real numbers from the session.
- Mines your conversation — 12-item extraction checklist covering goals, approaches, failures, decisions, measurements, code analysis, and user preferences
- Gathers external state — git log, diff, uncommitted changes, active tasks (in parallel)
- Detects chain continuity — finds prior handoffs in the same work stream, inherits chain tag and sequence number
- Validates the output — enforces line minimums by session size. If the first pass is too thin, it re-mines and expands
- Adapts to context size — at 500K+ tokens, switches to multi-pass map-reduce extraction to avoid the "lost in the middle" problem
Handoffs link across sessions automatically:
HANDOFF_fix-auth_2026-03-17.md (seq 1)
└─ HANDOFF_fix-auth_2026-03-18.md (seq 2)
└─ HANDOFF_fix-auth_2026-03-19.md (seq 3)
Your third session on a feature knows about the first two.
Claude already generates session summaries when context compresses. They look like handoffs — but they lack chain tracking, self-validation, evidence mining, and comprehension gates. In controlled A/B testing (same bug, same codebase, fresh sessions), the skill-based session:
- Required zero user intervention (the unstructured session needed "don't alter anything yet")
- Traced the complete failure call chain (the unstructured session proposed a surface-level fix)
- Found bugs not listed in the handoff through structured adjacent exploration
- Produced justified fixes instead of correct-but-unexplained ones
Without this, Claude may generate freeform "handoffs" when sessions end — documents that look right but skip the process. Add to your CLAUDE.md:
When ending a session or saving progress:
- ALWAYS use the /handoff skill. NEVER generate handoff summaries without it.The skills work standalone. They unlock more when paired with:
- Beads — Issue tracking in your repo. Handoffs auto-detect active beads and use them as chain tags.
- OpenViking — Persistent AI memory. Handoffs search for prior decisions and context from earlier sessions.
- Git — git log, diff, status gathered automatically.
- Any CLI task tracker — The skills use
bd(beads) as default — swap in Linear, Jira CLI, or GitHub Issues.
Safety net that runs before context compaction, capturing ~50 lines of git state and active tasks.
cp claude-handoff/hooks/precompact-handoff.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/precompact-handoff.shrm -rf ~/.claude/skills/handoff ~/.claude/skills/handoffplanMIT — If this saved you time, give it a star.