Handoff Guard
EvAlex/handoff-guard
Evita re-envios caros de contexto em sessões Claude Code frias
Ver no GitHubGuard macOS que alerta antes de digitar em uma sessão do Claude Code com cache expirado e migra seu trabalho para uma sessão fresca com um comando. Evita desperdício de tokens ao detectar sessões ociosas e oferece migração automática com histórico preservado.
Instalação
npx convez-ai EvAlex/handoff-guard1 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
Casos de uso
- Retomar sessões Claude Code depois de períodos de inatividade sem perder contexto
- Reduzir gastos com tokens ao detectar quando uma sessão perdeu cache e gerar handoff automático
- Automatizar migração de trabalho entre sessões sem perder conversas anteriores
Veredito

Ferramenta especializada e bem pensada para usuários frequentes do Claude Code em macOS que querem otimizar custos de token. Solução eficaz para um problema real (cache-cold sessions), mas limitada ao ecossistema Apple e dependente de formatos não-documentados.
README
A tradução para o português deste README ainda está na fila.
handoff-guard
Stop wasting tokens on cache-cold Claude Code sessions. handoff-guard warns you before you
type into a long-idle session and migrates your work into a fresh one with a single command.
macOS only (v1). Pure-Python, no dependencies beyond the
claudeCLI.
The problem
Claude Code's prompt cache goes cold after a session sits idle (~1h). Resuming that stale session re-sends the entire conversation as a cache miss — a large, avoidable token spend. It's cheaper to start a fresh session with a short handoff than to reanimate the old one.
What it does
Three surfaces, costing zero extra tokens until you actually migrate:
- Reactive guard — a
UserPromptSubmithook. If you submit a prompt to a session that's been idle past the threshold, it blocks the prompt and prints a ready-to-paste migrate command. (Submit again to override and continue anyway.) - Lazy generator —
claude-handoff. Generates a handoff from a session's transcript viaclaude -p --resume … --fork-session --model haiku(the original session is never mutated). Modes:--go(generate + open a freshclaudewith the handoff loaded),--print, or default (write a file + copy to clipboard + notify). - Proactive nudge — a launchd agent that posts a "session going cold" notification.
How it works
The source of truth is Claude Code's own per-process files ~/.claude/sessions/<pid>.json
(sessionId / status / updatedAt). A session is "idle" when its status is idle and
now − updatedAt exceeds the threshold.
Install
git clone https://github.com/evalex/handoff-guard.git
cd handoff-guard
./install.sh
This symlinks claude-handoff into ~/.local/bin, writes a default config, loads the
launchd agent, and safely registers the hook in ~/.claude/settings.json (with a backup).
Then check it:
claude-handoff doctor
Usage
When you return to a cold session and hit Enter, you'll see:
⚠️ This session has been idle 73 min. Continuing here re-reads the whole
context (expensive).
1) leave: Ctrl-C twice (or /exit)
2) run: claude-handoff --go <session-id>
Run that command in a terminal: it generates the handoff and opens a fresh claude with it
loaded — you just continue.
Configuration
~/.claude/handoff-guard/config.json (override the dir with HANDOFF_GUARD_HOME):
| Key | Default | Meaning |
|---|---|---|
enabled | true | Global kill switch (hook fails open, watcher no-ops) |
threshold_minutes | 60 | Idle minutes before a session is "cold" |
model | haiku | Model used to generate the handoff |
Uninstall
./uninstall.sh # removes hook, agent, symlink; keeps your config
./uninstall.sh --purge # also removes the data dir
Limitations
- macOS only. Uses launchd,
pbcopy,osascript. - Relies on the undocumented
~/.claude/sessions/<pid>.jsonformat, verified against Claude Code 2.1.x. If a future version changes it, the guard fails open (never blocks your input) and the watcher stays silent — runclaude-handoff doctorto check. claude-handoff --goneeds a real terminal (itexecs a new interactiveclaude).
Porting to Linux/Windows
The platform-specific seams are small and isolated:
- clipboard / notification:
_pbcopyand_notifyinsrc/handoff_guard/deliver.py - scheduler: the launchd plist +
install.sh(swap for cron/systemd or Task Scheduler)
PRs welcome.
Contributing
Issues and PRs welcome — especially Linux/Windows ports. Tests: python3 -m pytest tests/.
License
MIT © Alexander Pavlyuk