
handoff
Preserve and restore context between Claude Code sessions with always-on handoff hooks (auto-save before compaction, auto-inject after)
- version
- 0.2.0
- GitHub stars
- 12
Install
/plugin install handoff@handoffRun it inside Claude Code after adding the marketplace with /plugin marketplace add thepushkarp/handoff.
Contents
Discovered from sourceCommands 2
Create a comprehensive handoff document to preserve context for future Claude sessions.
Steps
-
Analyze Session Context Review the current conversation and gather:
- Current Task State: What is currently being worked on? What's in progress?
- Key Decisions: Important architectural or implementation choices made and their rationale
- Modified Files: Files that were changed during this session (check git log and git status if available, or recall from conversation)
- Blockers/Open Questions: Anything unresolved or blocking progress
- Next Steps: Clear, actionable items for the next session to continue
- Critical Context: Gotchas, edge cases discovered, important patterns, or anything the next session absolutely needs to know
- Model Summary: 8–12 bullets capturing the most important state/decisions/blockers
- Handoff Context: 10–20 lines of concrete “paste into next session” instructions (where to start, what to run, constraints)
-
Check Git Log and Status (if in a git repo) Run
git log --oneline --decorate --all --graphandgit statusto identify modified files. -
Read Existing Handoff (if any) Try to read docs/handoff/HANDOFF.md to check if it exists. If it does, you'll append to it.
-
Create Directory and Append Handoff Ensure docs/handoff/ directory exists with
mkdir -p docs/handoff, then append a new timestamped entry to docs/handoff/HANDOFF.md:--- ## Handoff: [TIMESTAMP] ### Current Task State [What was being worked on, current status] ### Key Decisions - [Decision 1]: [Rationale] - [Decision 2]: [Rationale] ### Modified Files - `path/to/file1.ts` - [brief description of changes] - `path/to/file2.py` - [brief description of changes] ### Blockers / Open Questions - [Any unresolved issues or questions] ### Next Steps 1. [First actionable item] 2. [Second actionable item] 3. [Third actionable item] ### Critical Context [Important gotchas, patterns, or context the next session needs] ### Model Summary - [8–12 bullets: goal, progress, key decisions, blockers, next steps] ### Handoff Context (paste into next session) [10–20 lines: actionable resume instructions, including file paths/commands] --- -
Confirm Handoff Created After writing, confirm the handoff was appended successfully and summarize what was captured.
Important Notes
- Be comprehensive but concise - capture what's necessary and sufficient
- Focus on information that would be lost during context compaction
- Include specific file paths, function names, and line numbers where relevant
- Prioritize actionable next steps over general observations
- If git is available, include recent commit hashes or branch info
Resume work from an existing handoff document at docs/handoff/HANDOFF.md.
Behavior
Default mode (no arguments): Display the handoff content and ask the user how they want to proceed.
Auto mode (--auto flag): Automatically inject the context and begin working on the next steps.
Steps
-
Check for Handoff File Read docs/handoff/HANDOFF.md if it exists.
-
Parse Most Recent Handoff The file may contain multiple handoff entries (appended with timestamps). Focus on the most recent handoff entry (the last
## Handoff: [TIMESTAMP]section in the file). -
Based on Mode:
If no arguments (default mode):
- Display a summary of the most recent handoff:
- When it was created
- Current task state
- Key decisions made
- Any blockers
- Next steps listed
- Ask the user: "How would you like to proceed? I can:
- Start working on the next steps
- Review the full handoff details first
- Do something else - please specify"
If
--autoflag provided:- Silently load the context
- Set up todos from the "Next Steps" section using TodoWrite
- Begin working on the first next step immediately
- Inform the user: "Resuming from handoff created at [TIMESTAMP]. Starting work on: [first next step]"
- Display a summary of the most recent handoff:
-
Handle Missing Handoff If docs/handoff/HANDOFF.md doesn't exist:
- Inform the user: "No handoff file found at docs/handoff/HANDOFF.md. Would you like to describe your current task so I can help you continue?"
Important Notes
- Pay attention to the "Critical Context" section - it contains gotchas and important info
- Respect any blockers mentioned - ask about their status before proceeding
- The "Key Decisions" section contains rationale that should guide continued work
- If multiple handoffs exist, you can offer to show history if user asks
Sponsors
Details
- Marketplace
- thepushkarp/handoff
- Source
- plugins/handoff
- Author
- thepushkarp
- Category
- Productivity
- Keywords
- handoff, context, session, continuity, workflow, compaction, hooks