Session handoff

The job

Turn everything learned in this session into one self-contained prompt the user can paste into a brand-new session (or hand to another agent) that knows nothing about this conversation, then put that prompt on their clipboard.

The whole value is that the future session has zero context. It cannot see this chat, your scratchpad, or your reasoning. If a fact isn't in the prompt (or reachable from a pointer the prompt gives), it's gone. Write for that reader.

Gather the real state first - don't hand back a template

A handoff prompt full of <fill this in> placeholders is useless. Before writing, collect the concrete state so the prompt is specific and true:

• Where the work lives - repo path, current branch, and git log --oneline -5 plus git status --short so you can name the exact commits and whether anything is uncommitted.
• What's done - the substantive results of this session, ideally anchored to commit hashes or file paths, not vibes.
• What's next - the specific next task, phrased as an instruction, not a mood.
• What to read first - the files, docs, and memories that hold the detail, so the prompt can point instead of dump.
• Gotchas and conventions - anything a fresh session would get wrong: how to run tests, "don't push", auth quirks, house style, tools to prefer.

Pull these from the actual conversation and the repo. When something is uncertain, check it (a quick git log, an ls) rather than guessing - a wrong fact in a handoff is worse than an omission because the next session will act on it.

Lean on pointers, keep it portable

The best handoff is short but complete because it delegates. If the project keeps notes or memory (design docs, NOTES.md, a memory system), tell the next session to read them first rather than re-explaining their contents. A prompt that says "read docs/foo-NOTES.md (authoritative) before touching anything" transfers more, more reliably, than three paragraphs paraphrasing that file. Dump raw detail only for things that live nowhere but this chat.

Use absolute paths so they're clickable and unambiguous in a fresh terminal.

Every pointer must outlive this session. A session scratchpad, or anything under /tmp or /private/tmp, can be gone by the time the next session starts: the scratchpad belongs to this session, and a reboot clears /tmp. You can still reach those files now, and the next session may not. So before writing the prompt, copy anything it needs somewhere durable - into the repo (uncommitted is fine, if the prompt says so) or a folder under the home directory - or paste it inline if it is short. Then point at the new location.

Prompt shape

Adapt to the work, but this structure covers most cases. Write it as if the user is speaking to the next session in the first person - that's how they'll paste it.

I'm resuming work on <project> in <absolute repo path> (branch <branch>).

## Context
<1-3 sentences: what this is and the current goal>

## What's done
- <result, with commit hash / file path where it applies>
- ...

## Read these first (authoritative - don't re-derive)
- <absolute path> - <why it matters>
- memory/notes: <where the durable state lives>

## Next task
<the specific next step, concretely enough to start immediately>

## Conventions / gotchas
- <how to run tests / build>
- <constraints: e.g. don't push; branch first; style rules>
- <anything a cold start would trip on>

Drop sections that don't apply; add one if the work needs it. Match the target tool's idiom - if the next session is Claude Code with skills/memory, say so and point at them; if it's a plain chat, make the prompt fully self-standing.

Put it on the clipboard

Write the prompt to a file, then pipe that file to the clipboard - this avoids shell quoting mangling multi-line text and backticks, and leaves a copy the user can re-grab:

# Pick whichever exists: pbcopy on macOS, clip.exe on Windows and WSL,
# xclip/wl-copy on a Linux desktop.
if command -v pbcopy >/dev/null; then pbcopy < /path/to/handoff-prompt.md
elif command -v clip.exe >/dev/null; then clip.exe < /path/to/handoff-prompt.md
elif command -v clip >/dev/null; then clip < /path/to/handoff-prompt.md
elif command -v wl-copy >/dev/null; then wl-copy < /path/to/handoff-prompt.md
elif command -v xclip >/dev/null; then xclip -selection clipboard < /path/to/handoff-prompt.md
else echo "NO_CLIPBOARD_TOOL"; fi

Prefer the session scratchpad directory for the file if one is defined; otherwise a temp path is fine.

Check the tool exists rather than assuming one. pbcopy is macOS only; clip.exe covers Windows AND WSL, because WSL executes Windows binaries. If none is found, say so plainly and print the prompt in a copyable block - a clipboard step that silently did nothing is the one failure the user cannot see, because they only find out when they paste stale content into the fresh session.

Close the loop

After copying, confirm it's on the clipboard and show the prompt in the chat too, so the user can eyeball it before starting fresh and tell you to adjust anything. Keep the confirmation to a line - the prompt itself is the deliverable.