claude-handoff: session handoffs for Claude Code

Never lose context between AI coding sessions. Claude Code skills and a Claude Code mod that write a structured session handoff: decisions, failed approaches, measurements, and next steps. Your next session, or the same one after compaction, picks up exactly where you left off. Stop wasting 20-40% of each session rediscovering what was already tried.

Now a Claude Code mod: /compact-handoff writes the handoff, swaps the conversation for it, and keeps working in the same terminal. No new window, no paste. Jump to the mod ↓

Install

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.

Usage

/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.

What you get

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.

/handoff vs /handoffplan

Both capture your session. The difference is what the next session does:

/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.

How it works

1. Mines your conversation — 12-item extraction checklist covering goals, approaches, failures, decisions, measurements, code analysis, and user preferences
2. Gathers external state — git log, diff, uncommitted changes, active tasks (in parallel)
3. Detects chain continuity — finds prior handoffs in the same work stream, inherits chain tag and sequence number
4. Validates the output — Phase 1 must hit the pass minimum on first write; Phase 2 then fills gaps toward the ceiling
5. 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.

Why this exists

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

Prevent skill shadowing

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.

Works with

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.

compact-handoff mod (experimental)

Runs the handoff, then replaces the conversation with it and keeps going in the same terminal, with no new session and no paste. It works like /compact, but the summary is your validated handoff.

claude plugin marketplace add REMvisual/claude-handoff
claude plugin install compact-handoff@claude-handoff

This also installs its small companion, compact-handoff-answer (see below). The skills above must be installed too, from v2.1.0 or later.

/compact-handoff [note]       # /handoff, then continue from "Where We're Going"
/compact-handoffplan [note]   # /handoffplan, then start executing Phase 1
/compact-handoff cancel       # drop a run that's stuck

What happens:

1. The skill runs in compact-mode: it asks nothing, commits the session's work, and writes the handoff (and plan).
2. When that turn ends, the mod checks the files on disk. If anything is missing, empty, interrupted or refused, the context is left untouched. It also counts the handoff's lines against the skill's minimum for the session's size (Chunked 500 lines from 500K tokens, Deep 300 from 100K). A short handoff gets one more turn to finish mining; still short, the context is left untouched.
3. The conversation is replaced by one short message naming the files. No summarizer call is made, so it takes milliseconds.
4. The skill's own paste prompt is sent automatically, so chain tracking continues (seq N+1).

While it runs, a bar above the prompt and the spinner line show how far along it is, for example Handoff 48% · Writing the handoff · 250 of 500 lines.

A handoff needs room: a large one adds up to about 80k tokens of context while it is written. The mod reads where Claude Code compacts on its own and warns as that room shrinks: at about 200k left, at about 100k, and when there is no longer room. With too little room, /compact-handoff does not start, because Claude Code would compact before the handoff was written. If Claude Code compacts on its own during a run, the mod ends the run and says no handoff was written.

The model can't start a handoff on its own while the mod is installed: its own call to /handoff or /handoffplan is refused, and it tells you to run /compact-handoff or /handoff instead. A handoff you ask for (typing /handoff, or "do a handoff" in your own words) runs as usual.

Why two plugins: Claude Code doesn't let a plugin answer a compaction it started itself. compact-handoff-answer is about 20 lines. It answers only compactions marked compact-handoff:v1 and leaves every other compaction alone.

Caveats:

• Experimental. The mod API is early access; tested on Claude Code 2.1.300.
• Where an organization manages Claude Code, compaction hooks from user-installed plugins don't run.
• Your own Stop and SessionStart hooks still run around the compaction, so slow ones add to the wait.
• Classic PreCompact hooks (including the one below) don't run on these compactions. SessionStart hooks with the compact matcher still do.

PreCompact hook (optional)

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.sh

Uninstall

rm -rf ~/.claude/skills/handoff ~/.claude/skills/handoffplan
claude plugin uninstall compact-handoff@claude-handoff
claude plugin prune    # removes compact-handoff-answer, installed as its dependency

License

MIT — If this saved you time, give it a star.