/handoff — save this conversation for a future session
Topic label (optional): $ARGUMENTS
Write a handoff file capturing the current state of this conversation so a future session
(with none of this context) can resume it with /pickup. Handoffs live in a central store so
many projects can coexist: $HANDOFF_DIR if set, otherwise ~/.claude/handoffs.
Steps
- Ensure the store exists and get a timestamp:
STORE="${HANDOFF_DIR:-$HOME/.claude/handoffs}"
mkdir -p "$STORE"
date +%Y-%m-%d-%H%M
- Build the slug (this is what
/pickup will match on, so make it descriptive):
- If a topic label was given in
$ARGUMENTS, kebab-case it (lowercase, spaces→-, strip punctuation).
- Otherwise infer a 2–4 word kebab slug from what this conversation is actually about.
- If the work centers on a specific repo/project, prefix the slug with that project's name
(e.g.
acme-web-deploy, acme-web-blocks). This keeps multiple projects distinct in the store.
- Write
$STORE/<slug>__<YYYY-MM-DD-HHMM>.md using the Write tool, following the
template below. Be concrete and specific — a stranger should be able to act from it alone.
- Confirm to the user: print the full file path and the exact resume command
/pickup <slug> (use the slug, not the timestamp — /pickup finds the latest match).
File template
# Handoff — <human title> (<YYYY-MM-DD HH:MM>)
- **Slug:** <slug> · **Resume with:** `/pickup <slug>`
- **Primary dir(s) / repo(s):** <absolute paths, e.g. ~/code/acme-web>
- **Related notes/docs:** <links or paths, if any>
## What this is about
<1–3 sentences: the goal and why.>
## Current state
<What's done and working right now. Be honest about what's half-done or unverified.>
## Key files & locations
<Absolute paths + one-line purpose for each file that matters. Include any URLs, ports,
running servers, or env vars in play.>
## Decisions made (and why)
<Bullets. Capture rationale so it isn't re-litigated. Note anything explicitly rejected.>
## Open questions / pending
<Anything awaiting a decision or blocked.>
## Next steps
<Ordered, actionable. The first item should be the obvious next thing to do.>
## Gotchas / environment
<Dev servers running, things that need the user's hands (auth, money), flaky steps, etc.>
Rules
- Don't dump the whole transcript — synthesize. Favor state, decisions, and next steps over narration.
- Use absolute paths so they resolve from any future cwd.
- Convert relative dates to absolute ("today", "yesterday" → real dates).
- Note any running processes / servers / URLs explicitly so
/pickup can re-verify them.
- If a handoff with the same slug already exists, append
-v2, -v3, … to the slug rather than overwriting (timestamps already differentiate, but keep slugs readable).
- Keep it tight — one screen or two. This is a launchpad, not an archive.
1---2name: handoff3description: Write a durable handoff summary of this conversation to disk so a future session can resume it cleanly with /pickup. Trigger with /handoff [topic label], or when the user says they're stopping for now, switching machines, or wants the current state saved for later.4---56# /handoff — save this conversation for a future session78Topic label (optional): $ARGUMENTS910Write a **handoff file** capturing the current state of this conversation so a future session11(with none of this context) can resume it with `/pickup`. Handoffs live in a central store so12many projects can coexist: `$HANDOFF_DIR` if set, otherwise `~/.claude/handoffs`.1314## Steps15161. **Ensure the store exists** and get a timestamp:17 ```bash18 STORE="${HANDOFF_DIR:-$HOME/.claude/handoffs}"19 mkdir -p "$STORE"20 date +%Y-%m-%d-%H%M21 ```222. **Build the slug** (this is what `/pickup` will match on, so make it descriptive):23 - If a topic label was given in `$ARGUMENTS`, kebab-case it (lowercase, spaces→`-`, strip punctuation).24 - Otherwise infer a 2–4 word kebab slug from what this conversation is actually about.25 - If the work centers on a specific repo/project, prefix the slug with that project's name26 (e.g. `acme-web-deploy`, `acme-web-blocks`). This keeps multiple projects distinct in the store.273. **Write** `$STORE/<slug>__<YYYY-MM-DD-HHMM>.md` using the Write tool, following the28 template below. Be concrete and specific — a stranger should be able to act from it alone.294. **Confirm** to the user: print the full file path and the exact resume command30 `/pickup <slug>` (use the slug, not the timestamp — `/pickup` finds the latest match).3132## File template3334```markdown35# Handoff — <human title> (<YYYY-MM-DD HH:MM>)3637- **Slug:** <slug> · **Resume with:** `/pickup <slug>`38- **Primary dir(s) / repo(s):** <absolute paths, e.g. ~/code/acme-web>39- **Related notes/docs:** <links or paths, if any>4041## What this is about42<1–3 sentences: the goal and why.>4344## Current state45<What's done and working right now. Be honest about what's half-done or unverified.>4647## Key files & locations48<Absolute paths + one-line purpose for each file that matters. Include any URLs, ports,49running servers, or env vars in play.>5051## Decisions made (and why)52<Bullets. Capture rationale so it isn't re-litigated. Note anything explicitly rejected.>5354## Open questions / pending55<Anything awaiting a decision or blocked.>5657## Next steps58<Ordered, actionable. The first item should be the obvious next thing to do.>5960## Gotchas / environment61<Dev servers running, things that need the user's hands (auth, money), flaky steps, etc.>62```6364## Rules6566- **Don't dump the whole transcript** — synthesize. Favor state, decisions, and next steps over narration.67- **Use absolute paths** so they resolve from any future cwd.68- **Convert relative dates to absolute** ("today", "yesterday" → real dates).69- Note any **running processes / servers / URLs** explicitly so `/pickup` can re-verify them.70- If a handoff with the same slug already exists, **append `-v2`, `-v3`, …** to the slug rather than overwriting (timestamps already differentiate, but keep slugs readable).71- Keep it tight — one screen or two. This is a launchpad, not an archive.
davemaynard