de una sola lectura: Un Gancho de Código Claude que Evita Lecturas Redundantes de Archivos

Un desarrollador ha creado un gancho PreToolUse llamado read-once que aborda la tendencia de Claude Code de leer repetidamente los mismos archivos durante una sesión, lo que consume tokens innecesarios.

El Problema y la Solución

Claude Code a menudo vuelve a leer archivos que ya tiene en contexto. Por ejemplo, abrir un archivo de 500 líneas, hacer una pequeña edición y hacer que Claude lea todo el archivo nuevamente cuesta aproximadamente 2,000+ tokens por lectura. En sesiones típicas, los mismos archivos podrían leerse de 5 a 10 veces.

El gancho read-once rastrea qué archivos ha leído Claude en la sesión actual. Cuando Claude intenta volver a leer un archivo sin cambios, el gancho lo bloquea y muestra un mensaje como: "read-once: config.rs (~3,400 tokens) ya está en contexto (leído hace 4m, sin cambios). Ahorro en sesión: ~12,000 tokens."

Cómo Funciona

• En la primera lectura: Registra la ruta del archivo, la hora de modificación y la marca de tiempo, luego permite la lectura normalmente.
• En la relectura de un archivo sin cambios: Bloquea la lectura ya que Claude ya tiene el contenido.
• En la relectura de un archivo modificado: En lugar de permitir una relectura completa, el gancho calcula la diferencia y devuelve solo lo que cambió. Claude ya tiene la versión anterior en contexto y solo necesita el delta. Para un archivo de 500 líneas donde cambiaron 3 líneas, esto usa ~30 tokens en lugar de ~2,000, ahorrando 80-95% en iteraciones de archivos.

Características y Configuración

La herramienta es consciente del TTL con entradas de caché que expiran después de 20 minutos (configurable). Después de la expiración, se permiten relecturas porque Claude puede haber compactado el contexto y perdido contenido anterior.

La configuración se realiza mediante variables de entorno:

• READ_ONCE_TTL=1200 - segundos antes de que expire el caché (predeterminado 20 min)
• READ_ONCE_DIFF=1 - habilitar modo de diferencias
• READ_ONCE_DIFF_MAX=40 - líneas máximas de diferencia antes de recurrir a relectura completa
• READ_ONCE_DISABLED=1 - desactivarlo por completo

Detalles Técnicos

Toda la herramienta tiene aproximadamente 250 líneas de bash sin dependencias más allá de jq y diff. Tiene licencia MIT y se instala agregándose a sus ganchos .claude/settings.json.

El desarrollador construyó esta herramienta porque ejecuta Claude Code en un bucle autónomo donde los costos de tokens se acumulan rápidamente. Solo el modo de diferencias supuestamente redujo su uso de tokens por sesión en aproximadamente un 30%.