context-save.sh

#!/usr/bin/env bash
set -euo pipefail
# tested with: claude code v2.1.122
# =============================================================================
# Context Save: PreCompact session handoff
# =============================================================================
# THE most important hook. Fires before Claude Code compresses context,
# generating a handoff markdown so you never lose your plan or progress.
#
# Hook type: PreCompact
#
# What it does:
#   1. Reads the JSON payload from stdin (contains session_id, transcript_path)
#   2. Creates .claude/handoff.md in the current working directory
#   3. Prints a message to stdout (injected into the conversation post-compact)
#
# After compaction, Claude Code will see the stdout message and can read
# the handoff file to restore context.
#
# You can customize the handoff template below to include project-specific
# sections (current branch, test status, TODO items, etc.)
# =============================================================================

# Read the hook payload from stdin
INPUT=$(cat)

# Parse fields from the JSON payload
SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "unknown"')
TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path // "not available"')

# Handoff file location (project-local)
HANDOFF=".claude/handoff.md"
mkdir -p .claude

# Capture environment context
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "not a git repo")
CURRENT_DIR=$(pwd)

# Write the handoff markdown
cat > "$HANDOFF" << EOF
# Session Handoff

**Auto-generated by PreCompact hook**
**Timestamp:** $(date -u +"%Y-%m-%dT%H:%M:%SZ")
**Session:** $SESSION_ID
**Working directory:** $CURRENT_DIR
**Git branch:** $CURRENT_BRANCH

---

## Context

This handoff was created automatically before context compression.
The full transcript is available at: \`$TRANSCRIPT\`

## What Was Happening

<!-- The hook cannot read Claude's mind, but the transcript has everything. -->
<!-- After compaction, Claude will see the stdout message below and can -->
<!-- read this file + the transcript to pick up where it left off. -->

Review the transcript above for the full conversation and task details.

## Resume Instructions

When resuming after compaction:
1. Read this file: \`$HANDOFF\`
2. Check git status for any in-progress changes
3. Review the transcript if you need full conversation history
4. Continue from where you left off

EOF

# This message gets injected into the conversation after compaction
echo "Context saved to $HANDOFF. read it to restore your plan and progress."

exit 0