A Claude Code plugin for preserving context, learnings, and state across agent sessions. When you're running low on context (~80% used), invoke /handover to create a living document that the next agent can pick up seamlessly.
This is specifically designed for long-running, big and complex tasks; to keep Claude on track. Tasks where a single session is not enough and auto-compact doesn't cut it.
This works for me much better than auto-compact. This helps also a messing-up agent to stop, reflect, and restart with learnings in a fresh context. In this case I just tell the agent "You messed up, we need to handover"; works great!
Note: This is not designed to make agents run forever autonomously; Quite the opposite: You are still in the driver seat. From my experience going full auto-pilot is a bad idea and never worked, hence why I designed this plugin and workflow instead.
- Living handover document (
.claude/handover.md) that accumulates learnings across generations - Context-aware statusline showing usage percentage and topic segmentation
- Suppressed issue tracking — catches when agents hide problems instead of fixing them
- Task preservation — captures in-flight tasks before session ends
- WIP commits — automatically commits current state so next agent can't accidentally revert
- Takeover skill — for when you forgot to handover and need to recover from a closed session
Nice status line to know when you have context-rot and should handover:
Tell Claude:
Read https://github.com/marcj/handover and install it in this project
Claude will read the repo, understand the installation steps, and set everything up for you.
THE HANDOVER CYCLE
==================
┌──────────────────────────────────────────────────────────────────────┐
│ │
│ SESSION N SESSION N+1 │
│ ───────── ─────────── │
│ │
│ Agent works Agent reads │
│ │ .claude/handover.md │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ │
│ │ context │ │ init │ │
│ │ fills │ │checklist│ │
│ │ up... │ └────┬────┘ │
│ └────┬────┘ │ │
│ │ ▼ │
│ │ ~80% used? continues work │
│ │ with full context │
│ ▼ │ │
│ ┌─────────┐ │ │
│ │/handover│ │ │
│ └────┬────┘ │ │
│ │ │ │
│ ├── gather context │ │
│ ├── extract learnings │ │
│ ├── capture tasks │ │
│ ├── scan suppressed issues │ │
│ ├── curate existing knowledge │ │
│ └── WIP commit │ │
│ │ │ │
│ ▼ │ │
│ ┌──────────────────┐ │ │
│ │.claude/handover.md │ │
│ │ │◄──────────────────────┘ │
│ │ • architecture │ │
│ │ • current state │ (living document that │
│ │ • learnings ⚠️✅ │ accumulates across │
│ │ • dead ends │ agent generations) │
│ │ • suppressed │ │
│ │ • tasks │ │
│ └──────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────┘
Knowledge compounds, not resets.
┌─────────────────────────────────────────────────────────────────────────────┐
│ SESSION 1 (Agent A) │
│ │
│ Work, work, work... │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Opus 4.5 │ 82% used (164k) ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░░░░ ● task A ● free │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ User: "Let's handover" │
│ │ │
│ ▼ │
│ ┌───────────────────┐ │
│ │ /handover │ │
│ │ │ │
│ │ • Gather context │ │
│ │ • Extract learns │ │
│ │ • Capture tasks │ │
│ │ • Scan issues │ │
│ │ • WIP commit │ │
│ └─────────┬─────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────┐ │
│ │ .claude/handover.md │
│ │ │ │
│ │ • Init checklist │ │
│ │ • Architecture │ │
│ │ • Current state │ │
│ │ • Next steps │ │
│ │ • Tasks │ │
│ │ • Learnings ⚠️✅ │ │
│ │ • Dead ends │ │
│ │ • Suppressed │ │
│ │ • Generation log │ │
│ └─────────┬─────────┘ │
└───────────────────────────────────┼─────────────────────────────────────────┘
│
│ (session ends)
│
┌───────────────────────────────────┼─────────────────────────────────────────┐
│ SESSION 2 (Agent B) │
│ │ │
│ User: "Read .claude/handover.md and continue" │
│ │ │
│ ▼ │
│ ┌───────────────────┐ │
│ │ Init Checklist │ │
│ │ │ │
│ │ 1. Read handover │ │
│ │ 2. Read CLAUDE.md │ │
│ │ 3. Read plan file │ │
│ │ 4. Run verify cmd │ │
│ │ 5. Recreate tasks │ │
│ │ 6. Verify learns │ │
│ │ 7. Check issues │ │
│ └─────────┬─────────┘ │
│ │ │
│ ▼ │
│ │
│ Agent B continues with full context, learnings, and task list... │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ Opus 4.5 │ 15% used (30k) ▒▒▒░░░░░░░░░░░░░░░░░ ● setup ● free │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
If you prefer to install manually (or Claude's install didn't work):
# In your project directory
mkdir -p .claude/skills/handover
curl -o .claude/skills/handover/SKILL.md https://raw.githubusercontent.com/marcj/handover/main/skills/handover/SKILL.md
# Optional: takeover skill for recovering from forgotten handovers
mkdir -p .claude/skills/takeover
curl -o .claude/skills/takeover/SKILL.md https://raw.githubusercontent.com/marcj/handover/main/skills/takeover/SKILL.mdOr for global installation (all projects):
mkdir -p ~/.claude/skills/handover ~/.claude/skills/takeover
curl -o ~/.claude/skills/handover/SKILL.md https://raw.githubusercontent.com/marcj/handover/main/skills/handover/SKILL.md
curl -o ~/.claude/skills/takeover/SKILL.md https://raw.githubusercontent.com/marcj/handover/main/skills/takeover/SKILL.mdThe statusline shows context usage and topic segmentation at a glance.
# Create statusline directory
mkdir -p ~/.claude/statusline
# Download the scripts
curl -o ~/.claude/statusline/ctx_monitor.js https://raw.githubusercontent.com/marcj/handover/main/statusline/ctx_monitor.js
curl -o ~/.claude/statusline/ctx_daemon.js https://raw.githubusercontent.com/marcj/handover/main/statusline/ctx_daemon.js
# Make executable
chmod +x ~/.claude/statusline/ctx_monitor.js ~/.claude/statusline/ctx_daemon.js
# Add to Claude Code settings
cat ~/.claude/settings.json | jq '. + {"statusLine": {"type": "command", "command": "~/.claude/statusline/ctx_monitor.js"}}' > /tmp/settings.json && mv /tmp/settings.json ~/.claude/settings.jsonOr manually add to ~/.claude/settings.json:
{
"statusLine": {
"type": "command",
"command": "~/.claude/statusline/ctx_monitor.js"
}
}When you're running low on context or ending a work session:
/handover
Or naturally mention it:
- "We need to handover"
- "Let's handover to the next agent"
- "You keep making the same mistake, we need to handover to a fresh agent"
The agent will:
- Gather context from the conversation
- Scan for suppressed issues (tests skipped, code commented out, etc.)
- Capture active tasks
- Propose learnings extracted from the session
- Curate existing knowledge (verify what's still relevant)
- Write/update
.claude/handover.md - Create a WIP commit
If you closed a session without running /handover:
/takeover
This will:
- Find recent session transcripts
- Let you pick which session to recover
- Run the handover protocol on that closed session
- Create the handover document retroactively
The next agent should begin with:
Read .claude/handover.md and continue the work
The handover document includes an init checklist the agent must follow.
.claude/handover.md contains:
- Init Checklist — steps the next agent must complete before starting
- Architecture Snapshot — high-level project structure (evolves slowly)
- Current State — branch, dirty files, failing tests, verification command
- Next Steps — prioritized task list
- Alignment Check — goal, scope boundary, plan file reference
- Tasks — captured from Claude's task list
- Learnings — accumulated knowledge (
⚠️ unverified, ✅ verified) - Dead Ends — approaches that didn't work
- Suppressed Issues — problems hidden instead of fixed
- Open Questions — unresolved technical decisions
- Generation Log — audit trail of all handovers
The statusline shows:
Opus 4.5 │ 82.0% used (164k) ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░░░░ ● handover skill ● statusline ● free
- Model name
- Context usage percentage and token count
- Visual bar with topic segments
- Legend showing what each segment represents
The segmentation is powered by a background daemon that calls Claude Sonnet via claude --print to analyze the conversation topics. It only re-analyzes when context increases by 10%+ and at least 60 seconds have passed.
The handover document is a living document — it's not just a snapshot, it accumulates knowledge across agent generations:
- Learnings are appended with each handover, marked as unverified (
⚠️ ) - Later agents can verify learnings against the codebase and mark them ✅
- Stale entries are pruned when the agent confirms they no longer apply
Agents sometimes "solve" problems by hiding them:
- Removing tests from whitelists
- Adding
.skipto failing tests - Commenting out problematic code
- Adding workarounds with "doesn't support yet" comments
The handover skill scans for these patterns and tracks them in the Suppressed Issues section. These can only be removed when the underlying issue is actually fixed.
The handover process is designed to be fast and non-intrusive:
- Agent extracts information from conversation context (no re-reading files)
- Agent proposes learnings instead of asking you to recall
- Agent curates existing entries by checking the codebase, not asking you
- Only asks for human judgment where needed (direction, scope)
In ctx_daemon.js:
const MIN_INTERVAL_MS = 60 * 1000; // 60 seconds between analyses
const MIN_PCT_DELTA = 10; // 10% context increase before re-analyzeThe daemon automatically shuts down after 10 minutes of inactivity:
const IDLE_TIMEOUT_MS = 10 * 60 * 1000;The daemon caches segments by session ID. If you see segments from another session:
rm ~/.claude/statusline/segment_cache.json
pkill -f ctx_daemon.jsCheck if it's running:
ps aux | grep ctx_daemonThe statusline auto-starts the daemon on first refresh. Check for errors:
node ~/.claude/statusline/ctx_daemon.jsThe statusline uses Claude's provided used_percentage from the input data. If there's a mismatch, check ~/.claude/statusline/debug_input.json (if debug logging is enabled).
MIT