/handoff — Session Handoff
Capture everything a fresh Claude session needs to continue this work without losing the thread.
When invoked, perform the following steps in order. Do not ask for confirmation — just execute.
Step 1: Gather Context
Collect the following (use Bash/Git/TaskList tools as needed):
- CWD —
pwdto know where the session is rooted - Project markers — does CWD or any ancestor contain
.git,package.json,CLAUDE.md, or similar? - Remote machines touched — scan the conversation for
ssh <host>invocations. List every host that was SSH'd into. This is critical for multi-machine sessions. - Files actually edited — the absolute paths of every file the session wrote to (local AND remote like
host:~/path/...) - Git state — only for the LOCAL CWD if it's a git repo (
git status --short+git log --oneline -5). Do NOT try to git-status remote paths. - Active tasks — check TaskList tool for in_progress or pending items
- Session audit — review the full conversation and identify:
- What was being built / worked on
- What is complete vs. in-progress vs. blocked
- Key decisions made, errors hit, approaches tried
- Next concrete action needed
Step 2: Classify the session and pick the write location
Use this decision tree EXPLICITLY. Do not guess. Print which path you took in the final output.
Path A: Local single-project session
Trigger: CWD is inside a project (has .git / package.json / CLAUDE.md ancestor) AND no remote machines were touched.
Write to: <project_root>/HANDOFF.md
Backup existing: if a HANDOFF.md exists with different # Handoff — <name> header, rename it to HANDOFF.md.bak.<YYYY-MM-DD-HHMMSS> first.
Path B: Generic CWD, single dominant project
Trigger: CWD is generic (~, /tmp, etc.) BUT 80%+ of file edits land in a single recognizable project directory.
Write to: that project's HANDOFF.md
Backup existing: same as Path A.
Path C: Multi-machine / multi-project / orchestration session
Trigger: ANY of the following is true:
- 2+ remote machines were SSH'd into
- Files were edited across 2+ different project directories
- The session built or modified things that don't have a single "home" directory (e.g., dispatching agents, infrastructure work)
Write to: ~/.claude/handoffs/HANDOFF-<slug>-<YYYY-MM-DD>.md (canonical archive) AND ~/HANDOFF.md (latest pointer copy).
<slug>is a kebab-case 2-4 word summary of the session.~/.claude/handoffs/— create withmkdir -pif it doesn't exist.- Both files have IDENTICAL content. The archive copy is for history; the
~/HANDOFF.mdcopy is the "latest" so the resume prompt has a stable path. - Before overwriting
~/HANDOFF.md, if its existing# Handoff — <name>header doesn't match the current session, MOVE it to~/.claude/handoffs/HANDOFF-<old-slug>-<old-date>.md.archive(preserve, don't delete).
Path D: Last resort
Trigger: None of the above match cleanly.
Write to: ~/HANDOFF.md and announce the choice clearly in the output.
Step 3: Write the HANDOFF file
Use this exact structure (adapt content, keep structure):
# Handoff — [Session Topic] — [YYYY-MM-DD]
> Read this at the start of the next session. Paste the Resume Prompt below as your first message.
## Session Type
- **Path used**: [A: Local single-project | B: Generic CWD single project | C: Multi-machine | D: Last resort]
- **CWD when written**: [absolute path]
- **Machines touched**: [list every SSH host, or "local only"]
## Scope
- **Project(s)**: [name + path. For multi-machine, list each: `host1:~/tools/foo/`, `host2:~/tools/bar/`, etc.]
- **Public URLs touched**: [if any are running services]
- **Local git** (only for local CWD if it's a repo): [branch, last commit, or "no git" or "remote-only session"]
## What We Were Doing
[2-4 sentences describing the task, goal, and current approach. Be specific enough that a fresh Claude
session can understand without reading the full history.]
## State
### Done
- [Completed item — be specific]
- [Completed item]
### In Progress
- [Current active work — where exactly it was left]
### Blocked / Pending
- [If any blockers or things waiting on external action]
## Next Steps
1. [Most immediate next action — specific file, function, command. Use absolute paths with machine prefix if remote: `host:~/path/to/file`]
2. [Second step]
3. [Third step if applicable]
## Key Files
| File | Role |
|------|------|
| `[absolute path with machine prefix if remote]` | [what it does or what changed] |
| `[absolute path]` | [what it does or what changed] |
## Context to Know
[Bullet list of non-obvious facts, gotchas, decisions, or environment notes a fresh session would
need. Skip anything obvious from the code itself.]
- [Context item]
- [Context item]
## Resume Prompt
Paste this as your first message in the new session:
---
Continuing work on [session topic].
Read HANDOFF.md at [ABSOLUTE PATH — never assume CWD] for full context.
Current task: [one-line description]
Next action: [specific first thing to do, with absolute paths]
---
Step 4: Confirm and Hand Off
After writing the file(s):
- Print which classification path was used (A/B/C/D) and why
- Print the FULL ABSOLUTE PATH(S) of every file written, on their own lines, copy-paste friendly
- Briefly summarize what was captured (3-5 bullets)
- Tell the user:
HANDOFF written. Primary:
<absolute path>[Archive:<archive path>(only for Path C)]Now run
/compactto compress context (keeps conversation, cheaper), or/clearto start completely fresh.In the new session, run
claudefrom any directory and say: "Read HANDOFF.md at "The path is absolute — it works regardless of where the new session starts.
Notes
- Keep the body under 100 lines — dense and actionable, not comprehensive. Future Claude can read code.
- The Resume Prompt is the most important part — it must be copy-pasteable and complete enough to orient a fresh session in under 10 seconds. ALWAYS use the absolute path of the HANDOFF file.
- Never assume the next session opens in a specific CWD — the user might start it from a different machine, a different terminal, a different directory. All paths in the handoff must be absolute.
- For remote files, use the
<host>:<path>notation (e.g.,mybox:~/tools/foo/.env) so the next session immediately knows it's not local. - Do not include this session's full conversation — distill it, don't transcribe it.
- If multiple projects were touched (Path C), they all live in ONE handoff document with sections per machine/project. Don't write multiple handoff files for one session — that fragments the context.
- Backup, don't overwrite blindly: if an existing HANDOFF.md is for a different project/session, rename it with a timestamp suffix before writing the new one.
