Cache Clock: vigila cuándo caduca la caché de prompt de Claude Code

Cache Clock es un mod de la comunidad de Hamza Zafar (hamzafer), parte de su colección claude-code-mods. Muestra el estado de la caché de prompt de Claude Code en una línea bajo la barra de estado. Mientras la caché está caliente, la línea es verde y se lee así: cache ● 1h ██████████ 59m left · hit 48% · misses 0. Son la duración de la caché (5m o 1h), una barra de diez celdas con lo que queda, el tiempo restante, la tasa de aciertos y el número de fallos.

Cuando queda menos del 20 % de la duración, la línea se vuelve amarilla. Cuando la caché ha caducado, pasa a rojo: cache ○ cold · next message re-caches 82k tokens, con la causa del último fallo si Claude Code la informa. La idea es ver, antes de enviar un mensaje, si se servirá desde la caché o si tendrá que pagar por reconstruir todo el prefijo.

Las cifras no las calcula el mod. Claude Code envía un objeto prompt_cache al comando de la barra de estado (desde la 2.1.251) y el mod solo le da formato. Los plugins no pueden registrar una barra de estado, así que el mod añade el comando /cache-clock: setup hace que statusLine apunte al script del mod y remove lo deja todo como estaba. Si ya tienes una barra de estado, se mantiene y la línea de caché va debajo.

La grabación inicia Claude Code con el mod cargado en el pequeño proyecto de demostración, con la barra de estado ya apuntada al script del mod; omitimos a propósito el paso /cache-clock setup para que la demo no escriba en el ~/.claude de quien graba. Se le pide a Claude que lea README.md y describa el proyecto en una frase. Mientras corre el turno, bajo el prompt aparece una línea verde cache ● 1h con la barra llena, 59m left y hit 0% · misses 0. Cuando el turno termina, la misma línea pasa a hit 48% · misses 0.

Usa cualquiera de los métodos del bloque de instalación; instalan directamente desde el marketplace del propio autor. Después ejecuta /cache-clock setup en una sesión. La línea aparece tras la siguiente respuesta de Claude, y /cache-clock a secas te dice si está activa.

hooks/register.ts registra el comando y hace la configuración. El statusline/cache-clock.mjs incluido es lo que Claude Code ejecuta en cada actualización de la barra de estado. Lee el JSON de stdin, ejecuta tu comando original si se guardó uno e imprime la línea de caché. El formateador puro está en statusline/render.mjs:

export function render(input, nowSeconds) {
  const cache = input?.prompt_cache
  if (!cache || typeof cache !== 'object') return ''
  if (cache.caching_observed === false) return ''

  const left = typeof cache.expires_at === 'number' ? cache.expires_at - nowSeconds : null
  const isWarm = cache.warm !== false && left !== null && left > 0
  return isWarm ? warmLine(cache, left) : coldLine(cache)
}

La línea cuenta como fría en cuanto pasa expires_at, aunque la entrada dijera caliente cuando se construyó. setup escribe los dos scripts en <config dir>/cache-clock/ en lugar de la carpeta del plugin, porque esa carpeta cambia con cada versión. En el siguiente inicio de sesión, refreshScripts sobrescribe las copias con las versiones nuevas si la barra de estado es la del mod. setup fija refreshInterval en 30 segundos, salvo que el tuyo ya sea menor, para que la cuenta atrás avance entre respuestas.

No hay opciones. /cache-clock setup y /cache-clock remove son los únicos interruptores. Para cambiar el aspecto, edita render.mjs: BAR_CELLS para el ancho de la barra, WARN_SHARE para el punto en que la línea se vuelve amarilla (20 % por defecto) y los códigos de escape de color al principio. Edita la copia de <config dir>/cache-clock/; mientras esté configurado, el mod la sobrescribe con la versión incluida en el siguiente inicio de sesión.

Antes de ejecutarlo leímos todos los archivos que el plugin ejecuta: .claude-plugin/plugin.json, hooks/hooks.json, hooks/register.ts, los dos scripts de la barra de estado y las pruebas. No hay package.json, script de instalación, código empaquetado o minificado ni binarios. El repositorio tiene un LICENSE MIT.

• Cambia ajustes solo si lo pides. Al instalar o iniciar sesión no se escribe nada, salvo refrescar sus propios scripts. /cache-clock setup escribe settings.json en tu carpeta de configuración de Claude (o CLAUDE_CONFIG_DIR), o <project>/.claude/settings.local.json cuando la barra de estado viene de los ajustes del proyecto. También escribe los scripts y una copia de seguridad setup-<hash>.json en <config dir>/cache-clock/. /cache-clock remove restaura la statusLine anterior, salvo que la hayas cambiado desde entonces. No toca barras de estado gestionadas (policy) ni las de --settings, y deja intacto un JSON de ajustes no válido.
• Ejecuta un comando en cada actualización. Tras el setup, Claude Code ejecuta node "<config dir>/cache-clock/cache-clock.mjs". Ese script ejecuta tu comando de barra de estado anterior mediante un shell (spawnSync(..., { shell: true }), 5 s de límite) con la misma entrada. El propio setup ejecuta node --version para comprobar que Node existe.
• Sin red, sin telemetría, sin llamadas al modelo, sin demonios. Lee HOME y CLAUDE_CONFIG_DIR solo para encontrar la carpeta de configuración. No lee tokens ni credenciales.
• Sin inyección de prompts ni hooks que bloqueen. Solo registra session.start y su propio comando, y no añade nada a los prompts ni a los resultados de herramientas.
• Requisitos: Node en el PATH y Claude Code 2.1.251 o posterior.

claude plugin validate no informó de errores ni avisos, y las 25 pruebas del autor pasaron con Claude Code 2.1.296.

Comprobado con Claude Code 2.1.296 en macOS (validate, pruebas y demo). Si la línea no aparece:

• Ejecuta /cache-clock. Debería decir “cache-clock is on”.
• Envía primero un mensaje. La línea está vacía hasta que llega prompt_cache, y también cuando el proveedor informa de que no hay caché.
• claude --version es 2.1.251 o posterior y node --version funciona en el mismo terminal.
• Tu barra de estado no viene de ajustes gestionados ni de --settings; el setup no los cambia.
• Tras hacer el setup en una sesión ya abierta, espera a la siguiente respuesta o a la actualización de 30 segundos.