| name | handover |
| description | Save session progress to a HANDOFF markdown and print a copy-pasteable pickup prompt. Use before `/clear`, when context is getting heavy, or when pausing work. Works for both repo-scoped and non-repo sessions. Produces a structured snapshot the next session can consume via the `pickup` skill. |
handover
Produce a handover document for this Claude Code session so work can resume cleanly after /clear or in a new session.
Where HANDOFF.md goes
Decide location by checking the session's working directory:
-
Inside a git repo (git rev-parse --show-toplevel succeeds): write to <repo_root>/HANDOFF.md. This keeps repo-scoped work next to the code.
-
Not in a git repo (home dir, ad-hoc session, etc.): write to ~/.claude/handovers/<slug>.md where:
<slug> = user-supplied label from the invocation argument (e.g. /handover memory-cleanup → memory-cleanup.md), OR<slug> = auto-generated from session content: kebab-case topic + date suffix (e.g. claude-mem-research-2026-04-22.md).- Create
~/.claude/handovers/ if it doesn't exist.
- Do not overwrite silently in this dir — if a file with the same slug exists, append
-2, -3, etc.
Always print the absolute path of the file you wrote.
Template
Write the file using these exact section headers — the pickup skill parses them:
# HANDOFF — <short task label> (<YYYY-MM-DD HH:MM>)
_Scope: <`repo:<name>` or `adhoc` (non-repo session)>_
## Goal
<One sentence: what this session was trying to accomplish.>
## Status
<What's done, what's in progress, what's not started. Be specific. No generalities like "made progress on X".>
## Files touched
- `path/to/file.ext` — <one-line reason>
- ...
(For ad-hoc sessions, list files across repos with absolute paths. For repo sessions, prefer repo-relative paths.)
## Key decisions
- Chose <X> over <Y> because <Z>.
- ...
## Open threads / blockers
- <Unresolved question, failing test, external dependency, etc.>
## Next step
<The literal next action. One specific actionable sentence. Not a list.>
## Don't do
- <Dead end already ruled out or user correction — so the next session doesn't retry it.>
Rules
- Secrets exclusion. No credentials, tokens, API keys,
.env/.ssh/wallet content in HANDOFF.md.
- Disk > chat. The summary goes in the file, not in chat.
- Terse. Bullets over prose. Specifics over generalities.
- Thin handovers are fine. If little happened, write it anyway — a skeleton is more useful than nothing.
- Repo handovers overwrite
HANDOFF.md in place. Ad-hoc handovers never overwrite — they suffix on collision.
Output to the user
After writing the file, print exactly this block and nothing else:
HANDOFF written: <absolute path>
Next: /clear, then /pickup <slug>
Where <slug> is the ad-hoc filename without the .md extension. For repo handovers (written to <repo_root>/HANDOFF.md), /pickup with no argument works — the pickup skill auto-detects ./HANDOFF.md from CWD.
The pickup skill does the reading, parsing, file re-reads (conditional on modification), and resumption from Next step — don't duplicate any of that guidance here. No paste-ready prompt needed; /pickup <slug> triggers the behavior.
No "here's what we did", no "let me know if...". Just the confirmation line and the Next command.
