Handoff

Compact the conversation into a file another session can read. Audience = a fresh agent with zero context: it gets this file plus whatever is on disk, nothing else. Optimize for that reader resuming work immediately, not for a human reliving the conversation.

Run before heavy auto-compaction when possible. If the conversation was already compacted, recover exact details from the raw transcript (below) where practical, and say the handoff derives partly from a summary — never imply completeness.

Session pointers

• Session ID: ${CLAUDE_SESSION_ID}
• Working dir: !pwd
• Transcript: locate with ls "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/projects/*/<session ID>.jsonl — session IDs are globally unique, so the match is the durable pointer. No match (disabled or cleaned up): omit the pointer lines rather than write a broken path.

Keep vs drop

Keep — verbatim where exactness matters:

• Unique findings: verified facts, API quirks, exact error messages, key file:line locations, IDs, numbers, URLs. These are the expensive-to-rediscover bits; never paraphrase an error message or truncate an ID to save space.
• Repo and environment state the fresh agent can't infer: which branch/worktree the work lives on, uncommitted or stashed changes, running dev servers/ports, env quirks.
• Decisions with the why, plus rejected alternatives worth not relitigating (one line each).
• Actions taken and their external side effects — distinguish drafted vs sent, local vs pushed.
• Dead ends a fresh agent would plausibly repeat.
• User constraints and preferences stated mid-conversation that aren't written down anywhere else.

Redact secrets. This file persists in scratch: credentials, tokens, cookies, and signed URLs get [redacted], even inside otherwise-verbatim errors.

Drop: tool-call play-by-play, resolved confusions, twists and turns, bulk detail that's cheap to re-derive from the repo or git history (keep the file:line pointers that lead there).

Expand every codename and shorthand the conversation invented — the reader wasn't there.

Template

# Handoff: [task title]

*From session `<session-id>` in `<cwd>`, <YYYY-MM-DD>.*

**You are a fresh agent picking up this work mid-stream.** Read this file, then start on the first Next step. Findings below are prior-session evidence — but reverify mutable external state (PRs, deploys, accounts) before acting on it.

## Goal
[1-2 sentences: what the user wants, why, and what "done" looks like.]

## State
[Task: done, in flight, broken. Machine: branch + worktree, uncommitted changes, running processes.]

## Findings
[Unique information unearthed. Verbatim errors/IDs/paths, secrets redacted.]

## Decisions
- [Decision] — [why; alternative rejected].

## Done
[Actions taken, with links and file paths.]

## Blockers
[Exact question or external condition being waited on. Omit if none.]

## Next steps
1. [The very next action, concrete enough to start cold.]
2. [...]

## Spelunking
- Raw transcript (durable): `<verified path>.jsonl` — grep it for anything this doc omits
- For the human: `claude --resume <session-id>` reopens the original session (from the original cwd, which may be gone if it was a temp worktree)

Sections are a menu: Goal, State, and Next steps always; omit the rest when empty rather than padding.

Workflow

1. Capture repo state (git branch --show-current, git status --short), then draft from the conversation. Target ~1 page; fidelity of Findings beats brevity.
2. Cold-reader check: reread as the fresh agent. Can it start Next step 1 without asking a question? Is every name, flag, and file it needs either defined here or on disk? If blocked, is the blocking question stated exactly? Fix gaps.
3. Write to ~/claude/scratch/handoff-<YYYY-MM-DD>-<slug>.md. Slug: lowercase [a-z0-9-], from $ARGUMENTS if given, else from the task. If the file exists, suffix (-2) — never overwrite an earlier handoff.
4. Tell the user the path and the import line to paste into the new session: Read ~/claude/scratch/handoff-<...>.md and continue from its next steps.