read-once: Um Gancho de Código do Claude que Evita Leituras Redundantes de Arquivos

Um desenvolvedor criou um hook PreToolUse chamado read-once que aborda a tendência do Claude Code de ler repetidamente os mesmos arquivos durante uma sessão, o que consome tokens desnecessários.

O Problema e a Solução

O Claude Code frequentemente relê arquivos que já estão em contexto. Por exemplo, abrir um arquivo de 500 linhas, fazer uma pequena edição e fazer o Claude ler o arquivo inteiro novamente custa aproximadamente 2.000+ tokens por leitura. Em sessões típicas, os mesmos arquivos podem ser lidos de 5 a 10 vezes.

O hook read-once rastreia quais arquivos o Claude leu na sessão atual. Quando o Claude tenta reler um arquivo inalterado, o hook bloqueia e exibe uma mensagem como: "read-once: config.rs (~3.400 tokens) já está em contexto (lido há 4m, inalterado). Economia da sessão: ~12.000 tokens."

Como Funciona

• Na primeira leitura: Registra o caminho do arquivo, horário de modificação e timestamp, então permite a leitura normalmente.
• Na releitura de arquivo inalterado: Bloqueia a leitura, pois o Claude já tem o conteúdo.
• Na releitura de arquivo alterado: Em vez de permitir uma releitura completa, o hook calcula o diff e retorna apenas o que mudou. O Claude já tem a versão antiga em contexto e só precisa do delta. Para um arquivo de 500 linhas onde 3 linhas mudaram, isso usa ~30 tokens em vez de ~2.000, economizando 80-95% nas iterações de arquivo.

Recursos e Configuração

A ferramenta é consciente de TTL, com entradas de cache expirando após 20 minutos (configurável). Após a expiração, releituras são permitidas porque o Claude pode ter compactado o contexto e perdido o conteúdo anterior.

A configuração é feita por variáveis de ambiente:

• READ_ONCE_TTL=1200 - segundos antes do cache expirar (padrão 20 min)
• READ_ONCE_DIFF=1 - ativar modo diff
• READ_ONCE_DIFF_MAX=40 - máximo de linhas diff antes de voltar à releitura completa
• READ_ONCE_DISABLED=1 - desativar completamente

Detalhes Técnicos

Toda a ferramenta tem aproximadamente 250 linhas de bash sem dependências além de jq e diff. É licenciada sob MIT e instala-se adicionando-se aos seus hooks .claude/settings.json.

O desenvolvedor construiu esta ferramenta porque executa o Claude Code em um loop autônomo onde os custos de tokens se acumulam rapidamente. Apenas o modo diff supostamente reduziu o uso de tokens por sessão em cerca de 30%.