convez.ai
HookProdutividadeIntermediário
andresleecom

Claude Handoff

andresleecom/claude-handoff

Preserva contexto e dead-ends entre sessões do Claude Code

Ver no GitHub
InicialPluginScore · de 0 a 100

Hook para Claude Code que fixa amnésia entre sessões, destilando decisões, dead-ends e próximos passos em um arquivo HANDOFF.md que é reinjetado automaticamente ao retomar. Elimina repetição de contexto e evita caminhos já explorados.

Instalação

$npx convez-ai andresleecom/claude-handoff

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 3 meses
Versão
v0.1.2
Issues abertas
0
Contribuidores
1

Casos de uso

  • Retomar projetos multi-dia sem perder contexto
  • Documentar caminhos já explorados para evitar repetição
  • Manter histórico de decisões técnicas e tentativas falhadas

Veredito

Solução prática e bem-pensada para um problema real do Claude Code: perda de contexto entre sessões. A ênfase em capturar dead-ends diferencia de outras abordagens. Implementação limpa (zero dependências, agnóstica a modelo), mas valor máximo para workflows iterativos e exploratórios.

README

A tradução para o português deste README ainda está na fila.

🤝 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


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

PieceEventWhat it does
inject.mjsSessionStart (startup/resume/clear/compact)Reads .claude/HANDOFF.md and injects it as context.
/handoffmanualThe live model (which already has everything in context) writes the best possible handoff.
capture.mjs → distill.mjsSessionEndSafety 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-handoffclaude-memmemory-toolkitCLAUDE.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)✅partialpartial✅

Configuration

Environment variableEffect
CLAUDE_HANDOFF_AUTO=0Disables the automatic safety net (manual /handoff only).
CLAUDE_HANDOFF_MODELModel 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

Ver o original no GitHub

Bom para

Relacionados