Usage Meter: medidor de limite de uso do Claude Code acima do prompt

O Usage Meter é um medidor de limite de uso do Claude Code, um mod da comunidade criado por Hamza Zafar (hamzafer), da coleção claude-code-mods dele. Ele desenha uma linha acima do prompt do Claude Code com as janelas de limite de uso do seu plano e o custo da sessão, por exemplo ⏱ 5h █▆▁▁▁ 34% · resets 2h10 · 7d ███▁▁ 61% · $0.42 session.

Cada janela ganha uma barra de cinco células feita com caracteres de bloco, então as células parciais mostram passos mais finos do que blocos inteiros mostrariam. A barra e a porcentagem ficam verdes abaixo de 75%, amarelas a partir de 75% e vermelhas a partir de 90%. A primeira janela (normalmente a de 5 horas) sempre mostra quando vai resetar. As outras, como a janela de 7 dias ou um limite de gastos, só mostram o horário de reset quando já estão altas. A contagem regressiva avança a cada minuto. Uma janela cujo horário de reset já passou fica escondida até o Claude Code informar uma leitura nova, então você nunca vê um 100% desatualizado.

Quando uma janela passa de 90%, um toast avisa você uma vez por período de reset, por exemplo 5h usage limit at 92%, resets in 1h05. Em um terminal estreito, a linha descarta primeiro as janelas secundárias e depois o custo, para que a janela principal sempre caiba. Sem assinatura (uma sessão com chave de API), não há janelas do plano e só o custo aparece.

Se você já usa o nosso Context Meter, a sobreposição está nos números de 5 horas e de 7 dias e no custo. O Context Meter escreve esses dados como texto na barra de status e acrescenta o preenchimento da janela de contexto; o Usage Meter os desenha como barras acima do prompt com uma contagem regressiva ao vivo e deixa o contexto de fora. O README do autor exige o Claude Code 2.1.287 ou mais recente.

A gravação inicia o Claude Code com o mod carregado, envia um prompt curto e mostra a linha acima do prompt depois do turno: as janelas do plano de 5 horas e de 7 dias como pequenas barras com as porcentagens, o tempo até o reset da janela de 5 horas e o custo da sessão. As barras do plano aparecem porque a conta da demonstração está conectada com uma assinatura do Claude.

Use qualquer um dos métodos do bloco de instalação; eles instalam direto do marketplace do próprio autor. Não é preciso configurar nada.

Estes são os dois hooks que fazem as leituras, de hooks/register.tsx:

on('session.start', async ($, e, next) => {
  const result = await next(e)
  // Moves the reset countdown on while a window has a reset time.
  timer?.cancel()
  timer = $.clock.every(TICK_MS, () => { /* bumps the tick atom */ })
  const usage = await $.session.usage().catch(() => null)
  if (usage) await take($, usage.rateLimits, usage.cost?.usd).catch(() => {})
  return result
})

on('session.measure', async ($, e, next) => {
  const result = await next(e)
  await take($, e.rateLimits, e.cost?.usd).catch(() => {})
  return result
})

take mantém as janelas com uma porcentagem finita, guarda-as em um átomo $.state mantido pelo host e chama warn, que mostra um toast para qualquer janela em 90% ou mais que ainda não tenha sido avisada no período de reset atual. Um horário de reset que avançou mais de meia hora conta como um novo período. O hook ui.render em AbovePrompt lê o snapshot e um átomo tick que o timer de 60 segundos incrementa, então a contagem regressiva é redesenhada sem uma nova leitura. As funções puras build, fit, bar, colorFor e countdown produzem os segmentos, e os testes do autor cobrem todas elas.

Não há opções no /config nem comando de barra. As constantes no início do register.tsx controlam os detalhes: CELLS (largura da barra, 5), TICK_MS (atualização da contagem regressiva, 60 segundos), WARN_AT (limite do toast, 90) e LABELS para os nomes das janelas (5h, 7d, spend).

Lemos todos os arquivos que o plugin pode executar antes de rodá-lo: hooks/hooks.json, hooks/register.tsx, as declarações de tipos e os testes. Não há package.json, script de instalação nem código empacotado.

Altera a interface cobre a linha acima do prompt e o toast de 90%. O mod lê os números de uso que o Claude Code já acompanha, via $.session.usage e o evento session.measure, e os mantém em $.state. Ele não executa comandos, não lê nem grava arquivos, não usa a rede, não lê variáveis de ambiente e não chama o modelo. O claude plugin validate não relatou erros nem avisos, e os 11 testes do autor passaram no Claude Code 2.1.291.

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

• claude --version é 2.1.287 ou mais recente.
• Você está usando uma assinatura do Claude. Com uma chave de API, só o custo aparece, e só depois que passa de $0.00.
• O Claude Code pode não ter números de uso até a primeira resposta do modelo. Envie um prompt e a linha é preenchida.
• Há uma pesquisa aberta acima da entrada; a linha volta depois que ela fecha.