Generate a structured session handoff document for seamless context transfer to a fresh session. Use when ending a session, switching tasks, or context is getting full.
Generate a compact handoff document for seamless context transfer to a new session.
Parse the topic from $ARGUMENTS. If no argument is provided, default to session.
Gather context by running these commands:
git diff --name-only to get changed filesgit log --oneline -5 to get recent commitsgit status --short to see uncommitted workCreate the handoffs directory if it doesn't exist:
mkdir -p .claude/handoffs
Generate the handoff document at .claude/handoffs/{YYYY-MM-DD}-{topic}.md using today's date and the topic. Use the Write tool.
The document MUST follow this exact structure:
# Handoff: {topic}
Date: {YYYY-MM-DD}
## Done
- {bullet points of completed work with file paths}
## In Progress
- {what's partially done, current state}
## Blocked
- {blockers or unknowns, or "None" if clear}
## Decisions
- {key decisions made and WHY — rationale matters for future sessions}
## Files Changed
- `{path}` — {one-line summary}
## Next Steps
1. {prioritized list of what to do next}
## Gotchas
- {anything the next session should watch out for}
Keep the document under 200 tokens. Be terse. Use short bullet points. File paths are more useful than prose. This is a reference document, not a narrative.
Confirm by outputting: "Handoff saved to .claude/handoffs/{filename}. Start a new session and run /resume to pick up where you left off."