Never lose context between AI coding sessions.
Session handoff skills for Claude Code that capture decisions, failed approaches, measurements, and next steps — so your next session picks up exactly where you left off. Save context, use fewer tokens, and 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: open Claude Code and type /handoff — it should appear in autocomplete.
/handoff # Capture session context into a structured file
/handoffplan # Capture context + generate an implementation plan
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 │
│ 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 single most expensive thing to rediscover across sessions. This section captures every attempt — what was tried, what happened, and why it was kept or abandoned — so the next session never repeats work.
See examples/ for full sample handoff and plan files.
The core skill. When you run /handoff, it:
- Detects context tier — automatically selects mining strategy based on conversation size. At 500K+ tokens (common on 1M context models), LLMs exhibit a "lost in the middle" problem where 30%+ of information in the middle of context gets missed. The skill compensates with multi-pass map-reduce extraction
- Mines your conversation using a 12-item checklist — goals, work completed, approaches tried, failed approaches, test results, decisions made, discoveries, code analysis, user preferences, remaining questions, and dependencies
- Gathers external state — git log, diff, uncommitted changes, active tasks from your tracker (in parallel using agent teams)
- Detects chain continuity — finds prior handoffs in the same work stream via task IDs, inherits the chain tag and sequence number
- Checks for stale references — verifies that code identifiers from prior handoffs still exist in the codebase
- Writes a validated file — enforces line minimums and data completeness. Tier 3 (massive sessions) enforces a 450-line floor. If the first pass is too thin, it goes back and mines deeper
- Generates a resume prompt — a paste-ready one-liner for the next session
Output: HANDOFF_{slug}_{date}.md in plans/handoffs/ or .claude/handoffs/
Runs the full /handoff first, then writes a paired implementation plan:
- Phased steps grounded in session evidence — every phase traces to findings from the handoff
- Anti-goals — what NOT to do, pulled from failed approaches and rejected alternatives
- Rollback strategy per phase — what to revert if things get worse
- Success criteria with baseline numbers from the handoff data
Output: PLAN_{slug}_{date}.md paired with the handoff file
A lightweight shell script that runs before context compaction, capturing ~50 lines of active tasks, recent commits, and uncommitted changes. Not a replacement for /handoff — a fallback so you never lose orientation completely.
Handoffs link across sessions via task or issue IDs:
HANDOFF_fix-auth_2026-03-17.md (seq 1)
└→ HANDOFF_fix-auth_2026-03-18.md (seq 2, parent: seq 1)
└→ HANDOFF_fix-auth_2026-03-19.md (seq 3, parent: seq 2)
Your third session on a feature knows about the first two. The resume prompt carries the chain tag and sequence number, so detection is automatic.
At 500K+ tokens, a single extraction pass demonstrably misses decisions and measurements from the middle of conversation (research). The skill automatically selects a mining strategy:
| Tier | Context size | Strategy |
|---|---|---|
| 1 | Under 100K | Single checklist pass |
| 2 | 100K–500K | Two passes: structured extraction + gap-fill for middle content |
| 3 | 500K+ | Map-reduce: chunk conversation, extract per-chunk, merge + validate |
The tier is announced at the start of mining ("Mining at Tier 3 — 1M context, 100+ tool calls"). Tier 3 enforces a 450-line floor — massive sessions cannot be adequately captured in fewer lines.
Every handoff runs through quality checks before it's written:
Standard (200K context):
| Session type | Minimum lines | Target range |
|---|---|---|
| Light (quick fix) | 80 | 80–120 |
| Medium (multi-step) | 120 | 120–180 |
| Heavy (testing, data, pivots) | 150 | 180–300 |
Extended (1M context):
| Session type | Minimum lines | Target range |
|---|---|---|
| Light (quick fix) | 120 | 120–200 |
| Medium (multi-step) | 200 | 200–350 |
| Heavy (testing, data, pivots) | 250 | 300–600 |
The skill auto-detects your context window size from the system prompt. If the draft is under the minimum, it re-mines the conversation and expands thin sections. Sessions over the split threshold (300 standard / 600 extended) split into cross-referenced parts.
Everything is optional — the skills work standalone and degrade gracefully. But they unlock more when paired with complementary tools:
| Tool | What it does for handoffs | Link |
|---|---|---|
| Beads | Issue tracking that lives in your repo. Handoffs auto-detect active beads, use bead IDs as chain tags, and update bead notes on close. The tightest integration. | Install beads |
| OpenViking | Persistent AI memory across sessions. Handoffs search OV for prior decisions, failed approaches, and context from earlier sessions — so chain continuity extends beyond what's in the handoff files. | Install OpenViking |
| Git | git log, git diff, git status for state gathering. Runs automatically when git is available. |
— |
Beads → tracks WHAT work needs doing (issues, deps, priorities)
OpenViking → remembers WHAT was learned (decisions, patterns, gotchas)
Handoff → captures WHERE you stopped (state, evidence, next steps)
Beads gives handoffs their chain tags. OpenViking gives handoffs prior context. Together, a new session can reconstruct the full picture: what's assigned, what was tried before, and exactly where to pick up.
- Any CLI task tracker — Linear, Jira CLI, GitHub Issues. The skill files use
bd(beads) as a concrete example — swap in your tracker's CLI. - Any memory/recall system — the skills search for prior context automatically when a recall tool is available.
Edit the skill files directly in ~/.claude/skills/handoff/skill.md:
- Line budgets — adjust minimums and target ranges per session type
- Output directory — default priority:
plans/handoffs/>.claude/handoffs/ - Chain tag resolution — adapt the logic to match your project's task ID scheme
- Handoff template — add or remove sections to fit your workflow
cp claude-handoff/hooks/precompact-handoff.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/precompact-handoff.shRegister as a PreCompact hook in your Claude Code settings. The script has no dependencies — it uses git and optionally your task tracker, skipping gracefully when unavailable.
rm -rf ~/.claude/skills/handoff ~/.claude/skills/handoffplan
rm -f ~/.claude/hooks/precompact-handoff.shHandoff files in your projects are yours to keep or delete.
See CONTRIBUTING.md.