claude-handoff
Health Warn
- License — License: MIT
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Low visibility — Only 8 GitHub stars
Code Pass
- Code scan — Scanned 5 files during light audit, no dangerous patterns found
Permissions Pass
- Permissions — No dangerous permissions requested
This tool provides a set of Claude Code skills designed to capture and preserve context between AI coding sessions. It generates structured handoff files summarizing decisions, failed approaches, and next steps, allowing fresh sessions to seamlessly resume previous work.
Security Assessment
Overall risk: Low. The tool consists of simple shell scripts and text-based skill files that are copied directly into your local Claude configuration directory. The automated code scan reviewed 5 files and found no dangerous patterns, hardcoded secrets, or network request attempts. While it inherently interacts with local conversation context and reads git state to generate its reports, it requests no dangerous system permissions and appears to operate entirely locally.
Quality Assessment
The project is very new and currently has low community visibility with only 8 GitHub stars, meaning it has not been broadly battle-tested by a wide user base. However, it is actively maintained (the most recent push was today) and the codebase safely operates under the permissive and standard MIT license. The provided documentation is highly detailed, clearly explaining its use cases and exactly how the installation process works.
Verdict
Safe to use, though the small community footprint means you should quickly review the script files yourself before installing.
Never lose context between AI coding sessions. Especially valuable at 500K+ tokens — when you've built up massive context and need to move to a fresh session without losing decisions, conversation style, user focus, failed approaches, and measurements. Structured handoffs with chain tracking for Claude Code.
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.
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: open Claude Code and type /handoff — it should appear in autocomplete.
Usage
/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.
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 │
│ 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.
How it works
/handoff — Context capture
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/
/handoffplan — Context capture + action plan
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
PreCompact hook — Safety net
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.
Chain tracking
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.
Context-aware mining (new in v1.3)
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.
Self-validation
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.
Works great with
Everything is optional — the skills work standalone and degrade gracefully. But they unlock more when paired with complementary tools:
Recommended stack
| 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. |
— |
How the stack fits together
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.
Other integrations
- 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.
Customization
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
PreCompact hook setup
cp claude-handoff/hooks/precompact-handoff.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/precompact-handoff.sh
Register 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.
Uninstall
rm -rf ~/.claude/skills/handoff ~/.claude/skills/handoffplan
rm -f ~/.claude/hooks/precompact-handoff.sh
Handoff files in your projects are yours to keep or delete.
Contributing
See CONTRIBUTING.md.
License
If this tool saved you time, give it a star. It helps others find it.
Reviews (0)
Sign in to leave a review.
Leave a reviewNo results found