ctx-handoff: sessões longas do Claude Code sem dor de cabeça

ctx-handoff é um mod da comunidade criado por CabLate (cablate) para as sessões longas do Claude Code, ou seja, conversas que duram horas. Ele reúne várias tarefas que surgem nelas: enquanto você está fora, envia uma requisição minúscula para o cache do prompt não expirar; transforma suas instruções repetidas em notas por projeto, carregadas nas conversas novas; e dá um aviso ao Claude quando ele repete uma ferramenta que falha ou diz «pronto» sem ter verificado nada.

Duas funções maiores são menos automáticas. Um handoff opcional escreve um resumo do trabalho, limpa a conversa e continua numa nova quando o contexto chega a um limite; ele vem desativado. Guardas são verificações de chamadas de ferramentas que o mod rascunha a partir de regras que você repete, e só valem depois que você as aprova. Um painel acima do prompt (/handoff panel) lista guardas, memórias, regras, a última atualização de notas e todas as configurações.

O README do autor mira assinaturas do Claude e sessões longas com contexto grande. Com chave de API, Bedrock ou Vertex o cache dura só cinco minutos, então o autor sugere /handoff refresh off.

A gravação inicia o Claude Code com o mod carregado no pequeno projeto de demonstração. O rodapé mostra logo ctx-handoff: 30 more messages until notes update, a contagem regressiva até a próxima atualização de notas em segundo plano. Em seguida roda /handoff guard, que imprime Guards: none com as condições em que guardas são rascunhadas, e /handoff refresh, que imprime Currently on. Usage: /handoff refresh on|off. O clipe não faz nenhuma requisição ao modelo e não abre o painel, porque ele mostra o caminho completo do arquivo de notas.

Use qualquer um dos métodos do bloco de instalação; eles instalam direto do marketplace do próprio autor. Inicie uma sessão nova e execute /handoff. A contagem regressiva do rodapé aparece quando a sessão começa.

Tudo é registrado a partir de um único módulo, hooks/register.ts. Cada turno concluído reinicia um temporizador de ociosidade. Quando ele dispara e o contexto está acima de min_tokens, o mod envia uma requisição fork mínima para ler a conversa em cache e agenda a próxima. Esta é a função de agendamento, de hooks/register.ts:

async function schedule($: EngineInterface, delay = cfg.idleMs) {
  rt.idle?.cancel()
  if (await awayPaused($)) { rt.idle = undefined; await update($, idleState, () => null); return }
  rt.idle = $.clock.after(delay, () => void onIdle($))
  const due = (await $.clock.now()) + delay
  await update($, idleState, () => ({ due, refreshes: rt.refreshes }))
}

Por padrão a ociosidade é de 50 minutos e há no máximo 3 atualizações; depois disso um handoff de ausência é salvo sem limpar. A cada 30 mensagens do usuário, ou antes de um handoff, uma requisição separada, sem histórico, envia só a parte nova da conversa a um modelo de notas (claude-sonnet-5-5, esforço baixo). As ações em JSON dele são validadas em código, as citações do usuário precisam aparecer nas suas mensagens reais, e linhas que parecem segredos são descartadas antes de qualquer gravação. As notas são injetadas nas conversas novas por meio de prompt.context.

O mod não declara userConfig. As configurações ficam na aba de configurações do painel (/handoff panel e depois a tecla 5), e o mod também lê pluginConfigs["ctx-handoff@<marketplace>"].options do settings.json; o valor do painel prevalece. Elas incluem auto_handoff (desativado por padrão), threshold (600000 tokens), idle_minutes (50), max_refresh (3), min_tokens (30000), distill_every (30), notes_model, retry_nudge, done_check, reply_language e language. Os comandos com barra cobrem o resto: /handoff now, dry, distill on|off, refresh on|off, away pause|resume, guard, resume, continue e resend.

Lemos o manifesto, hooks/hooks.json, hooks/register.ts por inteiro e os módulos de configurações, notas, handoff, guardas, laços, idioma, promoção e o prompt de destilação. Os demais arquivos, principalmente as strings de i18n, a visão do painel e pequenos auxiliares de registros, foram verificados por buscas para detectar efeitos colaterais, sem leitura linha a linha. O repositório não tem package.json, script de instalação, binário nem código minificado. tools/ contém scripts do autor que o plugin não carrega e que não executamos. Não há caracteres Unicode ocultos.

O que você deve saber:

• Requisições ao modelo, nenhuma outra rede. Não há fetch, chamadas de processo nem código de rede. O mod chama $.model.fork e $.model.complete, que usam sua cota do Claude. O texto da conversa é enviado para as notas e os resumos de handoff, do mesmo jeito que a própria conversa.
• Grava fora do próprio armazenamento. $.fs.write cria e atualiza <pasta de configuração do claude>/projects/<espaço de trabalho>/memory/ctx-handoff.md e grava um backup em .ctx-handoff-backup/ antes de apagar uma nota pelo painel. As atualizações de notas em segundo plano vêm ativadas, mas são puladas quando a sessão começa na sua pasta pessoal. Ele não mexe em settings.json, arquivos de shell nem LaunchAgents, e lê HOME, USERPROFILE e CLAUDE_CONFIG_DIR.
• Injeta texto no modelo. prompt.context adiciona às conversas novas suas notas, um memorando de progresso opcional e perguntas sobre guardas, marcados com [ctx-handoff]. Resultados de ferramentas podem trazer lembretes. Quando uma regra se repete 3 vezes em um repositório git, o texto injetado manda o Claude escrevê-la no repositório (CLAUDE.md, .claude/skills, hooks) sem perguntar, mas sem fazer commit. As notas são resumos das suas conversas escritos pelo modelo, então confira o arquivo de vez em quando.
• Hooks que condicionam. tool.call só pode negar uma chamada por causa de uma guarda que você aprovou. classic.Stop pode bloquear uma resposta de «pronto» por turno quando arquivos foram editados e nenhuma verificação rodou (done_check, ativado por padrão). prompt.submit retém suas mensagens enquanto um handoff está em andamento. Se você ativar o handoff automático, o mod executa /clear e envia o resumo sozinho.
• Sem daemon e sem telemetria. Os temporizadores existem só no processo do Claude Code. As estatísticas de uso ficam no armazenamento do plugin.
• Ambientes gerenciados. Segundo o claude plugin validate, os hooks prompt.context e classic.Stop não rodam em um plugin instalado pelo usuário quando uma organização gerencia o Claude Code.
• Licença. MIT, com arquivo LICENSE.

O claude plugin validate não relatou erros. O único aviso é que o CLAUDE.md na raiz do repositório não é carregado como contexto do plugin. Os 290 testes do autor, em 15 arquivos, passaram no Claude Code 2.1.303.

Verificado com o Claude Code 2.1.303 no macOS (validate, testes e a gravação). O README do autor exige 2.1.287 ou posterior. Se /handoff não fizer nada:

• claude --version é 2.1.287 ou posterior e você iniciou uma sessão nova depois de instalar.
• Pode já existir outro comando /handoff; nesse caso o mod registra /ctx-handoff.
• A contagem regressiva do rodapé não aparece se as atualizações de notas estiverem desativadas ou se você iniciou o Claude Code na sua pasta pessoal.
• As atualizações de cache só ajudam onde o cache dura uma hora, então com chave de API desative-as com /handoff refresh off.
• Execute /handoff para ver o estado atual, incluindo a última falha e o caminho do arquivo de notas.