Session Handoff

Session Handoff

Mid-session reset. Distinct from: /done (end-of-day), /gsd-pause-work (active GSD phase — prefer that; see Step 2a), /gsd-session-report (retrospective telemetry). Use when context is hot, a /clear is needed, and conversation state isn't yet on disk.

Persisted handoffs live at ~/.claude/handoffs/-.md, with latest.md as a pinned copy. A SessionStart hook surfaces latest.md if /dev/null && git log -5 --oneline 2>/dev/null && git diff --stat HEAD 2>/dev/null && \ echo "=== planning ===" && (ls .planning/phase-/PLAN.md .planning/phase-/SUMMARY.md 2>/dev/null | tail -10 || echo "no .planning")

The date (`YYYY-MM-DD`) comes from `currentDate` in the session reminder — don't shell out for it. Only the wall-clock `HH:MM` needs `date`.

**Conversation side — the cognitive step. This is the value of the handoff.**

Walk this checklist. Each bucket maps to a tag or section in the block:

- `[mcp]` **mcp-writes**: Notion/TickTick/NotebookLM/Actual Budget drafts not yet pushed → At-risk row
- `[vault]` **vault-writes**: Obsidian writes drafted in chat, not yet appended (CONTEXT.md, _decisions-log.md, hub, atomic note) → At-risk row
- `[memory]` **memory-pending**: memory rules discussed but not yet saved to MEMORY.md → At-risk row
- `[deferred]` **deferred**: Y from "do X then Y" still pending → At-risk row
- **decisions**: concrete choices locked this session → "Decisions locked" section
- **open-Qs**: decisions waiting on the user's input → "Open questions" section

### 2. Decide path

**2a. Active GSD phase? → delegate to `/gsd-pause-work` (if installed).**

Detection: `PLAN.md` exists in `.planning/phase-*/` but no `SUMMARY.md` in the same dir = phase active.

If yes, also check whether GSD is installed in this repo: `test -f ./.claude/get-shit-done/VERSION`.

- **GSD installed**: stop and output: "Active GSD phase at ``. Use `/gsd-pause-work` (phase-aware, produces PAUSE.md) — or confirm to proceed with session-handoff." Don't continue until confirmed; don't silently produce a parallel handoff.
- **GSD not installed**: stop and output: "Active GSD phase detected at ``, but GSD is not installed in this repo (`.claude/get-shit-done/VERSION` missing). Run `/gsd-install` to enable `/gsd-pause-work`, or confirm to proceed with session-handoff instead." Don't continue until confirmed.

**2b. Pick mode.**

- `--minimal` flag OR context monitor at critical → **minimal** (Step 3b)
- Otherwise → **default** (Step 3a)

### 3a. Write the handoff — default mode

Save via the **Write** tool to `~/.claude/handoffs/-.md` (e.g., `2026-04-26-2247.md`. `currentDate` from the session reminder, `HHMM` = `HH:MM` with the colon stripped).

Format below. **Sections with count = 0 are omitted entirely.** Situation, the `**Checked:**` line, and "Pick up from here" always render.

Session Handoff —

CWD: Project: | GSD phase N | other> Git: , modified, untracked, last commit "" Checked: decisions() at-risk() open-Qs()

Situation (2–3 sentences)

Decisions locked

At-risk state

• [mcp]
• [vault]
• [memory]
• [deferred]

Open questions

Pick up from here

1. Re-read first:
2. Next action:
3. Context not captured in files:

### 3b. Write the handoff — minimal mode

Same path scheme as 3a. Optional `-min` suffix to distinguish.

Format — keep under ~80 tokens:

Session Handoff (minimal) —

CWD: | Git: , +

Situation: Next action: Not on disk:

No tables, no Checked line, no section headers beyond the three bold labels.

### 4. Push to clipboard and pin as latest

One Bash call (substitute `` with the file written in Step 3):

```bash
pbcopy .md && \
cp ~/.claude/handoffs/.md ~/.claude/handoffs/latest.md && \
find ~/.claude/handoffs -name "????-??-??-????.md" -mtime +10 -delete && \
echo "Saved → ~/.claude/handoffs/.md (latest.md updated, clipboard ready, >10d pruned)"

Confirm with one line. Do not re-emit the block in chat — it's in the Write tool result and on disk.

5. Stop

After the clipboard copy, STOP. Do not continue working. Do not ask "what next?" — the user will /clear. The next session's SessionStart hook will surface latest.md automatically (if <2h old); otherwise paste from clipboard or read the file.

Style rules

• One section per question. "What isn't landed?" → at-risk. "What was decided?" → decisions. "What's blocked on the user?" → open-Qs. Don't fragment.
• "Context not captured" / "Not on disk" is the most important field in either mode. What did the user say in this conversation that isn't in any file?
• Don't editorialize. Next-session-you doesn't need commentary, just pointers.
• Don't re-list files. The **Git:** header line + git status in the next session beats any table.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ozlar34
• Source: ozlar34/claude-code-skills
• License: MIT
• Homepage: https://github.com/ozlar34

Install and usage instructions live in the source repository linked above.