claude-handover

Two Claude Code skills that let a session survive /clear: handover writes a structured HANDOFF.md, pickup reads it and resumes the work.

Designed for the moment your context window gets heavy, you need to swap tasks, or you're about to /clear and want to come back without losing the thread.

---

What it does

/handover [label]

Snapshots the session to disk in a parse-able format:

• Inside a git repo → <repo_root>/HANDOFF.md (overwrites in place)
• Outside a repo → ~/.claude/handovers/<label>.md (never overwrites — suffixes -2, -3 on collision)

The file uses fixed section headers (Goal, Status, Files touched, Key decisions, Open threads / blockers, Next step, Don't do) so pickup can parse it reliably.

After writing, Claude prints exactly:

HANDOFF written: /abs/path/to/HANDOFF.md

Next: /clear, then /pickup <slug>

/pickup [label|path]

Resumes from a HANDOFF file. Resolution order:

1. /pickup list → lists all ad-hoc handovers by mtime, plus notes whether ./HANDOFF.md exists.
2. /pickup <label> → reads ~/.claude/handovers/<label>.md.
3. /pickup <absolute-path> → reads that path directly.
4. /pickup (no arg) → prefers ./HANDOFF.md in CWD, falls back to the most recent ad-hoc handover.

Once loaded, Claude re-reads any files listed under Files touched (disk > summary — files may have changed since the handover was written), prints a ≤5-line acknowledgment, then executes the Next step.

---

Why it exists

• /clear is the fastest way to keep a long day of Claude sessions cheap and coherent, but it wipes everything. A thin markdown snapshot on disk is enough to pick up where you left off — often more reliable than a bloated context.
• Two skills instead of one so the write side and read side can evolve independently, and so pickup works even on HANDOFF files that weren't produced by this skill (as long as they follow the section headers).
• The ad-hoc directory (~/.claude/handovers/) means you can run handovers from non-repo sessions (the home dir, random scratch work) and still pick them back up later by label.

---

Install

As a Claude Code plugin (recommended)

From any Claude Code session:

/plugin install https://github.com/vmihalis/claude-handover.git

Manual install (symlink)

If you'd rather track updates with git pull:

git clone https://github.com/vmihalis/claude-handover.git ~/claude-handover
ln -s ~/claude-handover/skills/handover ~/.claude/skills/handover
ln -s ~/claude-handover/skills/pickup   ~/.claude/skills/pickup

Manual install (copy)

Simplest, no git dependency:

git clone https://github.com/vmihalis/claude-handover.git /tmp/claude-handover
mkdir -p ~/.claude/skills
cp -r /tmp/claude-handover/skills/handover ~/.claude/skills/
cp -r /tmp/claude-handover/skills/pickup   ~/.claude/skills/

Verify install — /help or a fresh session should list handover and pickup under available skills.

---

Usage walkthrough

You: [a long coding session, about to hit context limits]
You: /handover

Claude: HANDOFF written: /Users/you/repo/HANDOFF.md

        Next: /clear, then /pickup

You: /clear
You: /pickup

Claude: Goal: Migrate auth middleware to the new session-token schema.
        Done: new schema landed in `auth/schema.ts`; tests green.
        Next: wire the middleware into the request pipeline in `server/app.ts`.

        [proceeds to execute the next step]

For non-repo sessions:

You: /handover memory-cleanup

Claude: HANDOFF written: /Users/you/.claude/handovers/memory-cleanup.md

        Next: /clear, then /pickup memory-cleanup

---

HANDOFF.md format

# HANDOFF — <short task label> (<YYYY-MM-DD HH:MM>)

_Scope: repo:<name>  (or `adhoc` for non-repo sessions)_

## Goal
One sentence: what this session was trying to accomplish.

## Status
What's done, what's in progress, what's not started. Specifics, not generalities.

## Files touched
- `path/to/file.ext` — one-line reason
- ...

## 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.

## Don't do
- Dead ends already ruled out so the next session doesn't retry them.

Section headers are fixed — the pickup skill parses them.

---

Rules baked into the skills

• Secrets exclusion. No credentials, tokens, API keys, .env / .ssh / wallet content ever land in HANDOFF.md.
• Disk > chat. The summary goes to the file, not to the response.
• Repo handovers overwrite HANDOFF.md. Ad-hoc handovers never overwrite — they suffix on collision.
• Disk > summary (pickup side). If files diverged since the handover, pickup trusts the files and mentions the divergence.
• Pickup respects Don't do. Entries there are not retried silently.
• Pickup never deletes. You decide when to clear handover files.

---

File layout

claude-handover/
├── .claude-plugin/
│   └── plugin.json         # plugin manifest
├── skills/
│   ├── handover/
│   │   └── SKILL.md
│   └── pickup/
│       └── SKILL.md
├── LICENSE
└── README.md

---

License

MIT. See LICENSE.