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@handoff

Run it inside Claude Code after adding the marketplace with /plugin marketplace add thepushkarp/handoff.

Contents

Discovered from source

Commands 2

Create a comprehensive handoff document to preserve context for future Claude sessions.

Steps

  1. 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)
  2. Check Git Log and Status (if in a git repo) Run git log --oneline --decorate --all --graph and git status to identify modified files.

  3. 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.

  4. 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]
    
    ---
    
  5. 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

  1. Check for Handoff File Read docs/handoff/HANDOFF.md if it exists.

  2. 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).

  3. 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:
      1. Start working on the next steps
      2. Review the full handoff details first
      3. Do something else - please specify"

    If --auto flag 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]"
  4. 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