Cache Clock: veja quando o cache de prompt do Claude Code expira

O Cache Clock é um mod da comunidade de Hamza Zafar (hamzafer), parte da coleção claude-code-mods. Ele mostra o estado do cache de prompt do Claude Code em uma linha abaixo da barra de status. Enquanto o cache está quente, a linha é verde e aparece assim: cache ● 1h ██████████ 59m left · hit 48% · misses 0. São a duração do cache (5m ou 1h), uma barra de dez células com o que resta, o tempo restante, a taxa de acertos e o número de misses.

Quando resta menos de 20% da duração, a linha fica amarela. Depois que o cache expira, ela fica vermelha: cache ○ cold · next message re-caches 82k tokens, com a causa do último miss quando o Claude Code a informa. A ideia é ver, antes de enviar uma mensagem, se ela será atendida pelo cache ou se vai pagar para reconstruir todo o prefixo.

Os números não são calculados pelo mod. O Claude Code envia um objeto prompt_cache ao comando da barra de status (a partir da 2.1.251) e o mod apenas o formata. Plugins não conseguem registrar uma barra de status, então o mod adiciona o comando /cache-clock: setup faz statusLine apontar para o script do mod e remove deixa tudo como estava. Se você já tem uma barra de status, ela continua e a linha do cache fica abaixo dela.

A gravação inicia o Claude Code com o mod carregado no pequeno projeto de demonstração, com a barra de status já apontada para o script do mod; pulamos de propósito a etapa /cache-clock setup para que a demo não escreva no ~/.claude de quem grava. Pede-se ao Claude que leia o README.md e descreva o projeto em uma frase. Enquanto o turno roda, abaixo do prompt aparece uma linha verde cache ● 1h com a barra cheia, 59m left e hit 0% · misses 0. Quando o turno termina, a mesma linha passa para hit 48% · misses 0.

Use qualquer um dos métodos do bloco de instalação; todos instalam direto do marketplace do próprio autor. Depois, execute /cache-clock setup em uma sessão. A linha aparece após a próxima resposta do Claude, e /cache-clock sozinho diz se ela está ativa.

O hooks/register.ts registra o comando e faz a configuração. O statusline/cache-clock.mjs incluído é o que o Claude Code executa a cada atualização da barra de status. Ele lê o JSON da stdin, executa o seu comando original se um foi guardado e imprime a linha do cache. O formatador puro está em 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)
}

A linha conta como fria assim que expires_at passa, mesmo que a entrada dissesse quente quando foi montada. O setup grava os dois scripts em <config dir>/cache-clock/ em vez de na pasta do plugin, porque a pasta do plugin muda a cada versão. Na próxima abertura de sessão, o refreshScripts sobrescreve as cópias com as versões novas se a barra de status for a do mod. O setup define refreshInterval como 30 segundos, a menos que o seu já seja menor, para que a contagem regressiva ande entre as respostas.

Não há opções. /cache-clock setup e /cache-clock remove são os únicos interruptores. Para mudar o visual, edite render.mjs: BAR_CELLS para a largura da barra, WARN_SHARE para o ponto em que a linha fica amarela (20% por padrão) e os códigos de escape de cor no início. Edite a cópia em <config dir>/cache-clock/; enquanto estiver configurado, o mod a sobrescreve com a versão incluída na próxima abertura de sessão.

Antes de executar, lemos todos os arquivos que o plugin executa: .claude-plugin/plugin.json, hooks/hooks.json, hooks/register.ts, os dois scripts da barra de status e os testes. Não há package.json, script de instalação, código empacotado ou minificado, nem binários. O repositório tem um LICENSE MIT.

• Altera configurações só quando você pede. Na instalação e ao abrir a sessão nada é gravado, exceto a atualização dos próprios scripts. O /cache-clock setup grava settings.json na pasta de configuração do Claude (ou CLAUDE_CONFIG_DIR), ou <project>/.claude/settings.local.json quando a barra de status vem das configurações do projeto. Também grava os scripts e um backup setup-<hash>.json em <config dir>/cache-clock/. O /cache-clock remove restaura a statusLine anterior, a menos que você a tenha alterado depois. Ele não mexe em barras de status gerenciadas (policy) nem nas de --settings, e deixa intacto um JSON de configurações inválido.
• Executa um comando a cada atualização. Depois do setup, o Claude Code executa node "<config dir>/cache-clock/cache-clock.mjs". Esse script roda o seu comando de barra de status anterior por um shell (spawnSync(..., { shell: true }), limite de 5 s) com a mesma entrada. O próprio setup executa node --version para verificar se o Node existe.
• Sem rede, sem telemetria, sem chamadas ao modelo, sem daemon. Ele lê HOME e CLAUDE_CONFIG_DIR só para achar a pasta de configuração. Não lê tokens nem credenciais.
• Sem injeção de prompt e sem hooks de bloqueio. Registra apenas session.start e o próprio comando, e não acrescenta nada a prompts ou resultados de ferramentas.
• Requisitos: Node no PATH e Claude Code 2.1.251 ou mais recente.

O claude plugin validate não informou erros nem avisos, e os 25 testes do autor passaram no Claude Code 2.1.296.

Verificado com o Claude Code 2.1.296 no macOS (validate, testes e demo). Se a linha não aparecer:

• Execute /cache-clock. Deve dizer “cache-clock is on”.
• Envie uma mensagem primeiro. A linha fica vazia até o prompt_cache chegar, e também quando o provedor informa que não há cache.
• claude --version é 2.1.251 ou mais recente e node --version funciona no mesmo terminal.
• Sua barra de status não vem de configurações gerenciadas nem de --settings; o setup não altera essas.
• Depois de fazer o setup em uma sessão já aberta, aguarde a próxima resposta ou a atualização de 30 segundos.