Context Handoff

Preserve full session context across Claude conversations. Pack the current session — decisions, reasoning, work state, behavioral contracts, what was ruled out and why — and load it into any new chat. The new session resumes as if the conversation never ended.

Works for you, your future self, your teammates, and parallel Claude sessions.

Commands

All commands that prompt for confirmation accept --yes / -y to skip. See the Aliases section for shorthand forms.

No-argument invocation

When /context-handoff is invoked with no subcommand, smart-route based on session state:

1. Check ~/.claude/handoffs/.active and .claude/handoffs/.active
2. Active pack found (updated <= 4 hours ago):

   "Resume [topic] from [X ago]? (y/n)"

   • Yes: run /context-handoff load [pack]
   • No: ask "Create a new session pack instead? (y/n)" — if yes, run /context-handoff pack
3. No active pack (or stale):

   "No active session. Save this conversation as a context pack? (y/n)"

   • Yes: run /context-handoff pack
   • No: show /context-handoff help

This is the recommended entry point for users who don't remember command names.

First-time onboarding

When any /context-handoff command is invoked and ~/.claude/handoffs/ does not exist:

Show this exactly once before executing the command:

context-handoff remembers your sessions. Decisions made, things tried and rejected, where you left off, how you like to work — all of it restored when you come back. Type /context-handoff help to see all commands.

Then execute the original command. Never show this message again once the directory exists.

This ensures first-time users understand what they're getting without reading the README first.

/context-handoff pack [--project]

Synthesize the current conversation into a context pack file.

Scope:

• Default: save to ~/.claude/handoffs/
• --project: save to .claude/handoffs/ inside the current git repo. If not in a git repo: error "Not in a git repo — cannot use --project scope"

Steps:

1. Infer the topic from the conversation (or ask the user if ambiguous)
2. Create the target directory if it doesn't exist
3. Stale session check: If ~/.claude/handoffs/.active (or .claude/handoffs/.active for --project) already exists and the last_updated timestamp in that pack file is 4 hours old or older, surface it before proceeding. When --project is active, check .claude/handoffs/.active first; if no cwd entry found there, fall back to ~/.claude/handoffs/.active. Use the first entry found. The same lookup order applies in step 5 when reading prior_session.

   "Previous session detected: [topic] (last updated X hours ago). Load it, discard it, or ignore and continue?"

   • Load: run /context-handoff load with that pack
   • Discard: delete .active and proceed
   • Ignore: proceed without clearing .active (user manages it)
4. Same-topic detection: Before generating the new pack file, compute the topic slug for the new pack. Topic slug: lowercase the topic string, replace spaces and special characters with hyphens, strip leading/trailing hyphens, truncate to 40 characters. Example: 'Auth Refactor (JWT)' → 'auth-refactor-jwt'. Check whether any file matching *-<topic-slug>.md already exists in the target directory. If found, surface it before proceeding:

   "A pack for this topic already exists: 2026-05-16-vibe-safe-release.md (last updated X ago, N updates). Update it or create a new one?"

   • Update: run /context-handoff update on that pack (rewrite with current session state, increment update_count)
   • New: proceed with creating a new dated file
5. prior_session auto-population: If .active exists and is valid (not stale), set prior_session in the new pack's frontmatter to the path of the currently active pack before writing.
6. CLAUDE.md seeding: Before synthesizing behavioral contracts from the session: a. Check if CLAUDE.md exists in the current directory or ~/.claude/CLAUDE.md b. If found, read it and extract any behavioral instructions (style, process, constraints) c. Seed these into behavioral_contracts prefixed with [CLAUDE.md] so they're distinguishable from session-derived ones
7. Integrity hash: After step 6 (CLAUDE.md seeding) completes, compute content_hash by normalizing the pack content (set content_hash: "") then SHA-256 hashing the UTF-8 LF-normalized bytes. Store the resulting hex digest in content_hash and write the file once. On