Monitor de Consumo do Claude Code

Uma janelinha flutuante que fica na sua tela mostrando o quanto você já consumiu do seu plano do Claude Code, sem precisar abrir o painel de uso toda hora.

Ela vive minimizada como uma bolinha com um rostinho e um anel de progresso em volta. Clicou, abre o painel. Clicou de novo, volta a ser bolinha.

O rostinho muda de humor conforme o consumo:

| Consumo | Cor | Rostinho | |---|---|---| | até 50% | verde | feliz | | 50 a 79% | amarelo | neutro | | 80 a 89% | laranja | preocupado | | 90% ou mais | vermelho | muito preocupado |

As telas acima estão em inglês porque o widget segue o idioma do Windows. Em uma máquina em português ele aparece em português sozinho.

O que ela mostra

Consumo: quanto do limite semanal já foi (estimado), o bloco de 5 horas atual, o gasto do dia, o ciclo e o ritmo por hora.

Projetos: em qual projeto seu consumo está indo, em porcentagem. Dá para ver os últimos 30 dias, todo o período, os dois lado a lado, ou o esforço histórico por commits. Também dá para escolher um projeto só e acompanhar apenas ele.

Requisitos

• Windows
• Node.js 18 ou mais novo
• Claude Code já em uso na máquina (é dele que os dados são lidos)

Instalação

npx claude-code-usage-widget

Isso copia o widget para uma pasta fixa do seu usuário, instala o ccusage, cria dois atalhos no Desktop e faz a primeira leitura.

Depois abra o atalho Widget Consumo, ou rode:

npx claude-code-usage-widget start

Comandos

| Comando | O que faz | |---|---| | npx claude-code-usage-widget | instala e configura tudo | | npx claude-code-usage-widget start | abre o widget flutuante | | npx claude-code-usage-widget usage | mostra o consumo em janela de terminal | | npx claude-code-usage-widget projects | mostra o consumo por projeto | | npx claude-code-usage-widget calibrate 45 | calibra com a porcentagem que o /usage mostrou | | npx claude-code-usage-widget uninstall | remove a instalação e os atalhos |

Como usar

• Clique esquerdo na bolinha: abre o painel. De novo: volta pra bolinha
• Arrastar: muda de lugar (a posição fica salva)
• Clique direito: abre o menu

No menu você escolhe Painel completo, Somente a barra ou Projetos, qual medida o painel de projetos exibe, acompanhar só um projeto, fixar aberto, calibrar, atualizar ou fechar. A janela fica sempre por cima das outras.

A calibração (importante)

A porcentagem do limite do plano não fica gravada no seu computador. Ela vem ao vivo dos servidores da Anthropic, e nenhum programa local consegue lê-la.

Então a barra aqui é uma estimativa: o programa soma o consumo real dos seus arquivos locais (via ccusage) e converte em porcentagem usando uma referência que você informa uma vez.

1. No Claude Code, rode o comando /usage
2. Botão direito no widget e escolha "Calibrar com o /usage..."
3. Digite a porcentagem de "Todos os modelos" e confirme

Ou pelo terminal: npx claude-code-usage-widget calibrate 45.

Refaça isso de vez em quando (uma vez por semana resolve) para a estimativa não ir desviando. O número oficial é sempre o do /usage.

Configurações

Tudo por variável de ambiente, sem precisar editar código:

| Variável | Padrão | O que faz | |---|---|---| | CCUW_LANG | segue o Windows | pt ou en | | CCUW_RESET_DAY | 3 (quarta) | dia em que o ciclo semanal reseta, 0 domingo a 6 sábado | | CCUW_RESET_HOUR | 6 | hora em que o ciclo semanal reseta, 0 a 23 |

Consumo x esforço: são coisas diferentes

O painel de projetos tem duas medidas, e vale entender por quê.

Consumo (em dólar) mostra onde seus tokens estão sendo gastos. É útil para não estourar o limite, mas só enxerga o período que ainda tem transcrição salva em disco: o Claude Code apaga as antigas periodicamente, e o ccusage lê exatamente esses arquivos. Na prática, costuma cobrir pouco mais de um mês.

Esforço (commits) mostra onde seu trabalho foi parar desde sempre. Sobrevive à limpeza, então alcança projeto antigo que já sumiu do consumo.

Se um projeto aparece com muitos commits e zero consumo, é porque você trabalhou nele antes da janela que ainda existe em disco. Não é bug.

Personalizando os seus projetos

Abra o classificador.js na pasta de instalação (%LOCALAPPDATA%\claude-code-usage-widget) e edite a lista PROJETOS no início do arquivo. Cada projeto tem:

• nome: como aparece no painel
• cor: azul, roxo, verde, ciano, amarelo ou cinza
• termos: pares [texto, peso]. Peso alto é sinal inequívoco (nome de repositório, de pasta). Peso baixo é palavra que também aparece de passagem em conversa de outro projeto. A conversa vai para quem somar mais pontos.
• repos: nomes das pastas dos repositórios git daquele projeto

Cuidado com termo curto e genérico: se a palavra aparecer como dado dentro de outro projeto, ela rouba a conversa. Prefira nome de repositório.

Deixe o Claude Code fazer por você

Se você usa Claude Code, cole o prompt abaixo que ele instala e configura tudo, inclusive descobrindo seus projetos sozinho:

Instale e configure o Monitor de Consumo do Claude Code pra mim:
https://github.com/Welberjr/monitor-consumo-claude

1. Rode "npx claude-code-usage-widget" para instalar. Ele confere o Node,
   instala o ccusage e cria os atalhos.

2. Varra meu computador procurando repositórios git (pastas .git) nos locais
   comuns: C:\Dev, Desktop, OneDrive\Desktop, Documentos. Para cada um, veja o
   nome da pasta, o remote e quantos commits tem.

3. Com base no que achar, personalize a lista PROJETOS no classificador.js
   dentro de %LOCALAPPDATA%\claude-code-usage-widget: agrupe os repositórios por
   projeto real (um mesmo projeto pode ter vários repositórios), escolha termos
   que identifiquem cada projeto nas minhas conversas e dê uma cor pra cada um.
   Cuidado com termos curtos e genéricos, que roubam conversa de outro projeto.
   Se dois repositórios forem cópias do mesmo projeto, deduplique comparando o
   hash do commit raiz.

4. Rode "node projetos-dados.js" nessa pasta para gerar os dados e me mostre o
   resultado para eu conferir se os projetos ficaram certos.

5. Por fim, me peça para rodar /usage e me diga o comando de calibração com a
   porcentagem que eu te passar.

Importante: o widget.ps1 precisa continuar salvo em UTF-8 COM BOM, senão os
acentos quebram na tela do Windows PowerShell.

Como funciona por dentro

• widget.ps1: a janelinha (PowerShell + WinForms, sem dependência externa)
• widget.vbs: abre o widget sem piscar janela de console
• dados.js: coleta o consumo e grava dados.json
• projetos-dados.js: coleta o consumo por projeto e grava projetos.json
• classificador.js: decide a que projeto cada conversa pertence
• comum.js: acha o ccusage e a pasta do Claude sem caminho fixo
• idioma.js e config.js: os textos de cada idioma e o ajuste do ciclo
• monitor.cmd e projetos.cmd: as mesmas informações em janela de terminal

O widget nunca chama o ccusage direto: ele lê os arquivos .json, que são atualizados em segundo plano. Por isso a janela não trava. A classificação das conversas fica em cache, então a primeira leitura demora alguns minutos e as seguintes terminam em segundos.

Aviso sobre os valores

Os valores aparecem em dólar equivalente de API. Se você está num plano de assinatura (Pro ou Max), você não paga isso: a mensalidade é fixa. Use os números como proporção, para saber onde seu consumo está indo.

Créditos

Construído em cima do ccusage, que faz a leitura dos dados de uso locais.

Licença

MIT