| name | context-handoff |
| description | Generate a context handoff document at the end of a session so the next session can pick up where this one left off. Auto-invoked when ending significant work, or manually via /handoff. |
Context Handoff
Generate a structured handoff document that preserves session context for the next Claude Code agent.
When to Invoke
- End of any session that made meaningful changes
- Before switching between machines
- When context window is getting large and a fresh session is needed
- User says
/handoff, "wrap up", "hand off", or "create a handoff"
Output Location
Write to: .claude/context-handoff.md
This file is checked by every new session via the MEMORY.md auto-load instruction.
Handoff Template
Write the handoff using this exact structure:
# Context Handoff
> Generated: YYYY-MM-DD HH:MM | Machine: [identifier] | Session: [brief label]
## What Was Done This Session
[Bullet list of completed work. File paths, not summaries.]
## Current State
- **Git**: [branch, clean/dirty, last commit hash + message]
- **Uncommitted changes**: [list or "none"]
- **Blocked on**: [anything that couldn't be completed and why]
## Next Steps
[Ordered list of what the next session should pick up. Include file paths and specific instructions.]
## Key Decisions Made
[Any architectural or approach decisions the next agent needs to know about to avoid re-litigating.]
## Files to Read First
[Top 3-5 files the next session should read to get oriented, in priority order.]
Rules
- Be specific -- file paths, commit hashes, line numbers. Vague handoffs are useless.
- Don't summarize the whole repo -- only include what changed THIS session.
- Include blockers -- if something failed or was skipped, say why.
- Keep it under 100 lines -- this is a handoff, not a novel.
- Always run
git status and git log -1 --oneline before writing the handoff to capture accurate state.
