Handoff

Handoff

Write a handoff document that captures the live, transient state of the current conversation so a fresh agent can resume without re-deriving it. Save the doc to a per-run path under the user's OS temp directory; output the path so the user can hand it to the next agent.

Output location

$TMPDIR/claude-handoffs/<UTC-timestamp>-<short-topic-slug>.md

Falls back to /tmp/claude-handoffs/ if $TMPDIR is unset. Create the directory if missing. The timestamp + slug names are collision-free and sort newest-last.

Print the absolute path to the user (the last line of your response). They will paste it into the next session's first message.

What goes in the doc

Frontmatter:

---
created: <ISO-8601 UTC>
source-cwd: <pwd>
source-branch: <git branch --show-current, if in a git repo>
next-focus: <user's argument, or "(unspecified)">
---

Then sections, IN THIS ORDER:

1. One-line summary

What is the next agent picking up? Single sentence. If the user passed an argument, this MUST reflect their intent for the next session, not a recap of the current one.

2. State of play

Three buckets, each with bullet points (omit empty buckets):

• Done — what's already shipped (merged PRs, closed tickets, applied edits with commit refs)
• In flight — what's mid-stream (open PRs by number+URL, branches with uncommitted work, background tasks still polling)
• Blocked — what's waiting on something the next agent or human needs to act on

For each in-flight item, name the next concrete action. ("Run gh pr merge 25" beats "Merge PR #25 when ready".)

3. Live state to capture (don't expect git/beads to have it)

This is the section that justifies the handoff existing at all. Include:

• Background tasks: any Bash run_in_background jobs you started, CronCreate schedules, Monitor streams, ScheduleWakeup timers. List the task ID, what it's waiting for, and where its output goes.
• Decisions made + rationale: any judgment calls you made that aren't visible from the diff/commit messages alone (e.g., "chose AskUserQuestion over plan-mode after probing ExitPlanMode behavior"). Cite WHY, not just what.
• Won't-fix / reclassifications: review findings you declined to fix with explicit reasoning. The next agent might re-encounter the same finding.
• Open questions you couldn't resolve and the user hasn't answered yet.

4. References (don't duplicate; point)

For each artifact the next agent should read:

• PR URLs: gh pr view <N> shows description + state
• Beads tickets: bd show <id> for in-progress / blocked work
• Commits: git log <range> for the recent history
• Memory files: ~/.claude/projects/<project-id>/memory/<file>.md for cross-session context
• Skill or plugin paths: ~/.claude/plugins/cache/<...>/SKILL.md
• External docs: full URLs (don't paraphrase what's at the link)

Do NOT duplicate content already in any of these. Quote a line only if the next agent absolutely needs that exact wording to make a decision.

5. Suggested skills for the next agent

Skills the next agent will likely want to invoke. Be specific to what's actually installed and relevant:

• If the user is in a git repo with open PRs → pr-review-loop
• If beads is initialized in the repo → beads:beads, beads:ready
• If pulling artifacts to/from cloud → relevant skill (gcp-oauth, etc.)
• The user can extend this list — include skills they've mentioned in this conversation

6. Resume command

Single line the user can paste into the next session as the opening message, e.g.:

Read the handoff at /tmp/claude-handoffs/2026-05-21T14-30Z-handoff-rebase-cto-review.md and continue from "In flight".

Rules

Reference, don't duplicate

If the information already lives in git, beads, or memory, link to it; do not paraphrase. The handoff is a bridge to those sources, not a replacement for them. A 50-line handoff that points at the right artifacts beats a 500-line one that retells the artifacts' contents.

Redact sensitive material

Before saving, scan the doc for:

• API keys, OAuth tokens, session tokens (anything matching common prefixes: sk-, gho_, ghp_, github_pat_, xoxb-, xoxp-, AKIA, ASIA, AIza, Bearer , etc.)
• Passwords, private keys, certificates
• Personally identifiable information unrelated to the work (real names, emails) IF the conversation surfaced any — replace with <redacted>
• Customer or company-internal identifiers if the next agent might be working in a public context

If anything sensitive can't be redacted without breaking continuity, NOTE it explicitly: <redacted: contact user for value>.

Sanitize the topic slug

When constructing <short-topic-slug> for the filename, replace any character that isn't alphanumeric or hyphen — especially /, ., .., leading dots, and whitespace — with -. This keeps the handoff document inside its intended directory and avoids path-traversal surprises if the slug is ever derived from untrusted input (PR titles, issue text, etc.).

Tailor to the user's argument

If the user passed /handoff <focus>, that's the driver for the doc. The "One-line summary" must match it; "State of play" should highlight what's relevant to that focus; "Suggested skills" should be picked for it. Don't dump the entire session if the user only wants to hand off one slice.

If the user passed no argument, write a general-purpose handoff covering whatever's in-flight.

Keep it scannable

The receiving agent will read this cold. Use clear headers, short paragraphs, and concrete action verbs ("Run X", "Read Y", "Decide whether to Z"). Avoid narrative-style retrospectives ("I was in the middle of...") in favor of structured bullets.

What NOT to include

• A blow-by-blow of the conversation history (the receiving agent doesn't need to retrace your steps)
• Full file contents that haven't changed (point at the file path instead)
• Internal monologue about why you tried something that didn't work (unless it informs what to do next)
• Praise/sentiment about the user or the work (irrelevant signal for the next agent)
• A "TL;DR" section — the One-line summary IS the TL;DR

After saving

Output to the user:

1. The absolute file path of the handoff doc
2. A one-line confirmation of what was captured ("Wrote handoff for PR #25 dogfood + open beads ticket fv0 to ...")
3. The Resume command (section 6 above) so they can copy-paste it

Do NOT output the full handoff content in your message — the user can read the file. Keep your final message short.