convez.ai
ComandoAutomaçãoIntermediário
EvAlex

Handoff Guard

EvAlex/handoff-guard

Evita re-envios caros de contexto em sessões Claude Code frias

Ver no GitHub
InicialPluginScore · de 0 a 100

Guard 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-guard

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
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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 claude CLI.

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:

  1. Reactive guard — a UserPromptSubmit hook. 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.)
  2. Lazy generator — claude-handoff. Generates a handoff from a session's transcript via claude -p --resume … --fork-session --model haiku (the original session is never mutated). Modes: --go (generate + open a fresh claude with the handoff loaded), --print, or default (write a file + copy to clipboard + notify).
  3. 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):

KeyDefaultMeaning
enabledtrueGlobal kill switch (hook fails open, watcher no-ops)
threshold_minutes60Idle minutes before a session is "cold"
modelhaikuModel 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>.json format, 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 — run claude-handoff doctor to check.
  • claude-handoff --go needs a real terminal (it execs a new interactive claude).

Porting to Linux/Windows

The platform-specific seams are small and isolated:

  • clipboard / notification: _pbcopy and _notify in src/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

Ver o original no GitHub

Bom para

Relacionados