Skip to content

README.md

Latest commit

 

History

History
143 lines (94 loc) · 6.45 KB

README.md

File metadata and controls

143 lines (94 loc) · 6.45 KB
Raw

🤝 claude-handoff

Your Claude Code session forgets everything when you close it. This fixes that.

It distills every session into a readable HANDOFF.md — decisions, dead ends, and next steps — and re-injects it automatically when you resume. No more cross-session amnesia.

License: MIT Version Zero dependencies Cross-platform Clones

claude-handoff demo: work and hit dead ends, close, then resume the next day with the decisions and dead ends remembered

The problem

You close Claude Code. You come back tomorrow. The conversation is gone: the decisions you made, the three things you already tried that didn't work, what was left to do. You re-explain everything. Or worse: Claude walks back into the same dead end you already ruled out.

--continue reloads the whole conversation (and bloats it). /compact summarizes aggressively. CLAUDE.md has to be maintained by hand. None of them capture why something didn't work.

The solution

claude-handoff is a pure plugin (hooks + skill + markdown) that does two things:

  • On close → distills the session into .claude/HANDOFF.md: summary, decisions, dead ends, next steps, git state, and how to resume.
  • On resume → re-injects that handoff as context, automatically (including after a compaction).
During the session  ──  /handoff   ──▶  .claude/HANDOFF.md          (live model, best quality)
On close            ──  SessionEnd ──▶  distill in background  ──▶  .claude/HANDOFF.md   (safety net)
On resume/compact   ──  SessionStart ─▶  HANDOFF.md  ──▶  context restored

Install

In Claude Code:

/plugin marketplace add andresleecom/claude-handoff
/plugin install claude-handoff@claude-handoff

That's it. Zero dependencies, nothing to configure.

How it works

Piece Event What it does
inject.mjs SessionStart (startup/resume/clear/compact) Reads .claude/HANDOFF.md and injects it as context.
/handoff manual The live model (which already has everything in context) writes the best possible handoff.
capture.mjs → distill.mjs SessionEnd Safety net: if you forgot /handoff, it distills the transcript in the background with a cheap model (Haiku). It never blocks the close.

The handoff lives at .claude/HANDOFF.md and is added to your .gitignore by default: these are personal notes, they don't clutter the repo.

The format (the differentiator)

Other plugins store "memory". claude-handoff explicitly captures what you should not repeat:

# 🤝 Handoff — my-project
_Last updated: 2026-06-04 18:20 · Branch: feature/auth_

## 📝 Summary
Implementing login. The happy path works; token refresh is missing.

## ✅ Decisions made
- JWT in an httpOnly cookie — why: avoids exposing the token to JS.

## ⛔ Dead ends (do not repeat)
- In-memory session tokens → lost on server restart. Dropped.
- Refresh inside an axios interceptor → infinite loop on the 401. Abandoned.

## 🔜 Next steps
- [ ] POST /refresh endpoint with token rotation.

## 🌳 Git state
- Branch: `feature/auth`
- Uncommitted: src/auth/session.ts

## ▶️ How to resume
`npm run dev` and test login at /login. Start with src/auth/session.ts.

vs. other options

claude-handoff claude-mem memory-toolkit CLAUDE.md
Automatic capture on close ✅ ✅ ✅ ❌
Automatic re-injection on resume ✅ ✅ ✅ partial
Dead-end tracking ✅ ❌ ❌ ❌
100% human-readable (markdown) ✅ ❌ (DB) ✅ ✅
Git-aware (branch/commits/dirty) ✅ ❌ partial ❌
Zero dependencies ✅ ❌ ❌ —
Cross-platform (incl. native Windows) ✅ partial partial ✅

Configuration

Environment variable Effect
CLAUDE_HANDOFF_AUTO=0 Disables the automatic safety net (manual /handoff only).
CLAUDE_HANDOFF_MODEL Model for the background distiller (default claude-haiku-4-5-20251001).

FAQ

Does it work offline? Re-injection and /handoff do (they're local). The automatic safety net on close needs a model call.

How much does it cost? Re-injection and /handoff add no extra cost. The safety net uses Haiku (cheap) and only when you didn't write a fresh handoff. Disable it with CLAUDE_HANDOFF_AUTO=0.

Does it work on Windows? Yes. The hooks are pure Node.js (no bash/jq), tested on Windows, macOS, and Linux.

Does it commit HANDOFF.md? Not by default: it's added to .gitignore as personal notes. Remove it from there if you want to share it with your team.

How do I disable automatic capture? Set CLAUDE_HANDOFF_AUTO=0 in your environment. Re-injection and /handoff keep working.

Doesn't it loop by calling itself? No: the distillation uses claude -p --bare (no plugin auto-discovery) plus an anti-recursion environment guard.

Security

claude-handoff runs hooks automatically and spawns a background process, so it takes a few precautions — see SECURITY.md for the full threat model. In short: the background distiller validates CLAUDE_HANDOFF_MODEL against a strict whitelist (no command injection), high-confidence secret patterns are redacted before anything is written or re-injected, the handoff is gitignored by default, and re-injected content is framed as reference data, not instructions. Found something? Open a private security advisory on GitHub.

Roadmap

  • Per-branch memory (.claude/handoff/<branch>.md).
  • Token budget / selective injection.
  • PreCompact hook that refreshes the handoff before compaction.
  • Cross-tool support (other agents reading the same HANDOFF.md).
  • Handoff history and search.

Contributing

Issues and PRs welcome. The plugin is deliberately small and dependency-free; let's keep it that way.

License

MIT © Andres Lee