Token Weather: previsão do contexto do Claude Code em uma linha

O Token Weather é um mod da comunidade de Hamza Zafar (hamzafer), parte da coleção claude-code-mods dele. Ele traz uma previsão do contexto do Claude Code em uma linha acima do prompt: uma palavra do tempo com ícone para mostrar o quanto a janela está cheia, a porcentagem, os tokens em relação ao tamanho da janela, um sparkline dos últimos turnos e uma contagem regressiva de quanto tempo o cache de prompt continua quente.

A previsão vai de ☀ Clear (abaixo de 25%) passando por ☁ Cloudy, ☂ Showers e ☇ Storm até ↯ Compact soon a partir de 90%. Ao lado, last turns desenha até 12 leituras com ▁▂▃▄▅▆▇█, na escala da maior delas, seguidas de quanto o último turno aumentou ou diminuiu, como ▲ +39.4k last turn. Se a linha for larga o bastante, ❄ cache 4:12 faz a contagem regressiva até o cache expirar, fica amarelo no último minuto e depois mostra ❄ cache cold.

O Token Weather se sobrepõe às nossas páginas do Context Bar, do Context Meter e do Cache Clock. O Context Bar detalha a janela por categoria; o Context Meter coloca a porcentagem e o uso do plano na linha de status; o Cache Clock mostra detalhes do cache abaixo da linha de status. O Token Weather dá um veredito em uma linha e a tendência. O marketplace do autor o lista na versão 0.2.2.

A gravação inicia o Claude Code com o mod carregado no pequeno projeto de demonstração. Antes de qualquer prompt, a linha acima da entrada diz ☀ Clear 0% of context 0 / 1M. Em seguida pedimos ao Claude que leia o README.md e diga em uma frase o que é o projeto. Enquanto a primeira requisição roda, aparece uma contagem regressiva ❄ cache 5:00. Quando o turno termina, a linha mostra ☀ Clear 4% of context 39.4k / 1M, um sparkline, ▲ +39.4k last turn e ❄ cache 60:00, porque a resposta gravou um cache de uma hora.

Use qualquer um dos métodos do bloco de instalação; eles instalam direto do marketplace do autor. A linha aparece no início da próxima sessão. O plugin tem uma única opção: a duração do cache de prompt.

O mod guarda suas leituras em átomos $.state mantidos pelo host, então elas sobrevivem a um hot reload. Uma leitura é feita no início da sessão e depois de cada turno do agente principal, com os números de contexto de $.session.usage. O relógio do cache reinicia quando termina cada requisição de modelo da thread principal, inclusive as do laço de ferramentas dentro de um turno. Este é o manipulador de turn.step, de hooks/register.tsx:

on('turn.step', async function* ($, e, next) {
  const result = yield* next(e)
  if (!e.agentId && result.stopReason !== null) {
    const now = await $.clock.now()
    await update($, lastRequestAt, () => now)
    restart($, now, now, await ttlMsFor($, override))
  }
  return result
})

No modo auto, depois de cada turno ele lê o último megabyte da transcrição da sessão (<config dir>/projects/<project>/<session id>.jsonl) e procura tokens de 1 hora ou de 5 minutos em cache_creation na última resposta da thread principal. O resultado fica guardado no armazenamento do plugin para a próxima sessão. Um temporizador redesenha a linha quando o texto da contagem muda: a cada 30 segundos com mais de dez minutos restantes, a cada 15 segundos abaixo disso e a cada segundo nos últimos dois minutos.

A única opção é cacheTtl nas configurações do plugin: auto (padrão), 5m ou 1h. Um valor fixo tem prioridade sobre a detecção. As faixas da previsão, o histórico de 12 leituras e o aviso de 60 segundos são constantes no início de register.tsx. O mod também lê um arquivo de ordem opcional, <config dir>/claude-code-mods/bands.json, que define a ordem quando vários mods de faixas do mesmo autor se desenham acima do prompt.

Antes de executar, lemos todos os arquivos que o plugin pode executar: .claude-plugin/plugin.json, hooks/hooks.json, hooks/register.tsx, hooks/bands.ts, as declarações de tipos e os três arquivos de teste. Não há package.json, script de instalação, binário nem código empacotado, e o texto que ele desenha é montado a partir de números; nada é injetado no prompt do modelo. O repositório tem um LICENSE MIT.

O que ele faz, por completo:

• Rede: nenhuma.
• Processos: um, tail -c 1048576 <caminho da transcrição>, somente quando a transcrição passa de 1 MB. Caso contrário, lê o arquivo diretamente.
• Arquivos lidos: a sua própria transcrição de sessão (para detectar a duração do cache), o bands.json opcional no diretório de configuração do Claude e as configurações do Claude Code por $.settings.read (para ver se a linha de status do Cache Clock está definida). Ele lê as variáveis de ambiente HOME e CLAUDE_CONFIG_DIR para encontrá-los.
• Arquivos gravados: nenhum diretamente. Ele salva a duração de cache detectada (5m ou 1h) com $.store, o armazenamento próprio do plugin.
• Trabalho em segundo plano: um temporizador de redesenho dentro do Claude Code, que para quando a sessão termina. Sem daemon.
• Bloqueios: nenhum. Ele não bloqueia nem reescreve chamadas de ferramentas ou prompts.

O claude plugin validate não relatou erros nem avisos do próprio plugin (o verificador de diretório aponta a falta de um ícone). Os 24 testes do autor passaram no Claude Code 2.1.307.

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

• Você iniciou uma sessão nova depois da instalação; o mod é carregado no início da sessão.
• Não há uma pesquisa aberta acima da entrada. A linha dá lugar às pesquisas e volta depois.
• A janela tem pelo menos 60 colunas. Em terminais mais estreitos só aparecem a palavra do tempo, a porcentagem e os tokens.
• Se a contagem regressiva estiver errada, defina cacheTtl como 5m ou 1h em vez de auto. Um caminho de projeto muito longo ou um projeto movido durante a sessão pode impedir que a transcrição seja encontrada; nesse caso o último valor detectado permanece.
• Depois de /clear ou de retomar uma sessão, a contagem regressiva fica oculta até a próxima requisição.