handoff

Handoff Detection

At Session Start

Check the working directory for HANDOFF.md. If it's there:

1. Read it silently
2. Tell the user: "Found a handoff from a previous session: [title]. [1-sentence goal]. Resume from here?"
3. When they agree, follow /handoff:resume flow

Also check for HANDOFF-auto.md. If found and no HANDOFF.md exists, tell the user: "Found an auto-saved handoff from before context compaction: [title]. Resume from here?"

On Context Compaction

When Claude Code is about to compact context (PreCompact event), automatically save state without waiting for the user to invoke /handoff:create.

Steps when PreCompact fires:

1. Run git log --oneline -5, git status, and git diff --stat HEAD to capture current repo state
2. From conversation context, extract:
   • Current goal (what the session was trying to accomplish)
   • Completed items so far
   • In-progress work at the moment of compaction
   • Any known blockers or unresolved errors
3. Write to HANDOFF-auto.md in the repo root using the standard /handoff:create template
   • Never write to HANDOFF.md — do not overwrite a deliberate handoff
   • If HANDOFF-auto.md already exists, overwrite it (it is always the latest auto-save)
4. Prepend the file with this banner as the first line:

   > ⚡ Auto-saved before context compaction — [current date/time]
   > Resume with `/handoff:resume auto` to continue from this point.
   

5. Output a single confirmation line to the user:

   ✓ Context saved to HANDOFF-auto.md before compaction.
   

Edge cases:

• No git repo → skip git commands, still write what is available from conversation context
• HANDOFF.md exists → leave it untouched, write only to HANDOFF-auto.md

Trigger Words

Activate when the user says any of these:

• "handoff" / "hand off"
• "pass this to"
• "continue later" / "pick up where"
• "transfer context" / "save state"
• "resume" / "take over"

Offering Unprompted

Suggest a handoff when:

Condition	When to suggest
"I need to go" / "let's stop here"	User is wrapping up the session
Milestone reached	A significant feature or fix has just been completed
Long session with heavy context	Risk of context loss is growing

Ask: "Want me to create a handoff so you (or another agent) can continue later?"

Commands

Command	Use When	Intent
/handoff:create	Full handoff with all context	User is wrapping up or handing off to another agent
/handoff:quick	Simple handoff with just the basics	Task is small and minimal context is needed
/handoff:resume	Continue from existing handoff	User is starting a new session from a saved handoff

Route: wrap-up → create · simple task → quick · new session → resume