Claude-Handover: Solving the Context Loss Problem in AI Agent Sessions
A Claude Code plugin that creates structured handover documents between AI agent sessions, preserving context, failed approaches, and next steps so work can resume seamlessly.
If you've spent any meaningful time working with Claude Code on multi-session projects, you've hit this wall: you're deep into a complex refactor or debugging session, context limits hit or you need to step away, and when you start a new session everything is gone. The new agent doesn't know what you tried, what failed, or what the next step was supposed to be. You end up re-explaining context, the agent re-attempts approaches you already ruled out, and momentum evaporates.
Claude-Handover is a plugin I built to fix this. It creates structured handover documents between Claude Code sessions — machine-readable context files that let a new agent pick up exactly where the last one left off.
The Problem
Claude Code sessions are stateless. Each new session starts with a blank slate. CLAUDE.md files help with project-level context, but they don't capture session-specific state: what you were working on, what you already tried, what decisions were made and why, or what the immediate next steps are. The cost of this context loss compounds — it's not just lost time re-explaining, it's the agent repeating failed approaches or making different (possibly conflicting) architectural decisions.
How It Works
The plugin provides three commands:
/handover:create — Capture Current State
This spawns a dedicated subagent that performs a thorough investigation of the repository. It analyzes git status and recent commits, reviews diffs of uncommitted changes, searches for existing plans and task files, checks CLAUDE.md files for project context, runs the test suite, scans for error logs, and identifies active work areas. The output is a structured HANDOVER.md file at the repository root.
/handover:resume — Pick Up Where You Left Off
In a new session, this command reads the HANDOVER.md, internalizes all the captured context, removes the handover file (so it doesn't clutter the repo), and provides a concise summary of prior work before executing the documented resumption instructions. You can also pass focus hints — e.g., "/handover:resume focus on the failing tests first".
/handover:handoff — One-Step Session Transfer
This combines both steps: it generates the handover document and then automatically spawns a fresh Claude Code session with the resume command pre-loaded. One command and the baton is passed.
What Gets Captured
The generated handover document is specifically designed for AI agents, not humans. It prioritizes precision and actionability over readability. Each document includes:
Metadata — timestamp, agent model, git branch, last commit hash
Goal statement — what the prior agent was trying to accomplish
Progress tracking — tasks marked as completed, in progress, or not started
Build and test status — compilation state, test pass/fail counts
Uncommitted changes — summary of modified and staged files
Design decisions — architectural choices and their rationale
Failed approaches — what didn't work and why, so the next agent doesn't repeat them
Blockers — issues preventing progress, external dependencies
Critical files — specific file paths, function names, and line numbers
Resumption instructions — precise step-by-step guidance for the next agent
The "failed approaches" section is particularly valuable. Without it, a new agent will often re-attempt the same broken strategies, wasting time and tokens discovering the same dead ends.
Technical Implementation
The plugin uses Claude Code's plugin system with a clean structure: a plugin.json configuration, three command definitions (create, resume, handoff), and a dedicated handover-writer subagent. The writer agent runs on Sonnet with a 25-turn limit and has access to Read, Grep, Glob, Bash, and Write tools — enough to thoroughly investigate any repository state.
The investigation follows a systematic 7-step process: analyze git status, review diffs, search for existing plans, check CLAUDE.md files, run tests, scan error logs, and identify active work areas. Everything gets synthesized into the structured HANDOVER.md.
A nice detail: when resuming, the handover file is removed via git rm but not committed — it stays out of version history entirely. The handover document is ephemeral infrastructure, not project documentation.
Installation
The plugin can be installed via the Claude Code plugin marketplace or directly from GitHub:
/plugin install handover@danielrosehill/Claude-Handover --scope user
The repo is at github.com/danielrosehill/Claude-Handover — MIT licensed.