Monitor de uso do Claude Code – rastreador em tempo real para contornar limites de uso

• Ferramenta de monitoramento que mostra em tempo real no terminal várias informações, como uso de tokens do Claude AI, velocidade de consumo e previsão de esgotamento
• Barra de progresso colorida atualizada a cada 3 segundos, com previsão inteligente de esgotamento de tokens
• Ao ultrapassar o limite do plano padrão, analisa o histórico da sessão e muda imediatamente para o limite real
• Detecta e oferece suporte automaticamente a planos de uso como Pro/Max5/Max20/custom_max
• Alertas em tempo real quando o limite de tokens por sessão está próximo, é ultrapassado ou há risco de esgotamento antes do reset da sessão
• Interface implementada e otimizada para o fluxo real de uso do Claude
• Instalação via npm, pip, recomendação de uso de ambiente virtual (venv/virtualenv) e suporte a Mac/Linux/Windows

Entendendo as sessões do Claude

• Modelo de janela deslizante de 5 horas
  • A sessão permanece por 5 horas a partir do momento em que a primeira mensagem é enviada
  • O limite é aplicado por sessão, e várias podem ficar ativas ao mesmo tempo
  • O reset real acontece a cada 5 horas com base no horário das minhas mensagens
• É possível definir a referência de horário para reset de sessão/tokens de acordo com a sua agenda

Cenários de uso

• Desenvolvedores que começam cedo pela manhã: é possível ajustar o agendamento de reset de tokens ao início do expediente (por exemplo, 9h) para planejar com mais eficiência
• Quem trabalha à noite: pode usar um reset de tokens alinhado à própria rotina, como à meia-noite
• Usuários com limite variável: no modo custom_max, o limite é detectado automaticamente de acordo com o ambiente real
• Desenvolvedores globais/remotos: deslocamento entre vários fusos horários, definição do horário de reset por equipe → colaboração otimizada
• Verificação rápida de status: basta executar, independentemente da configuração

Melhores práticas para configurar o ambiente

• Inicie o monitoramento assim que a sessão começar
  • Ao iniciar um trabalho no Claude, execute o monitor imediatamente (./ccusage_monitor.py)
  • Planos compatíveis
    • pro: cerca de 7.000 tokens (testes e uso leve)
    • max5: cerca de 35.000 tokens (desenvolvimento do dia a dia)
    • max20: cerca de 140.000 tokens (projetos grandes e uso de média/alta intensidade)
    • custom_max: modo de detecção automática (usa o valor máximo com base no histórico real de uso)
  • Melhora a precisão do rastreamento de tokens da sessão inteira
  • Permite calcular a taxa de consumo de tokens e alertar cedo quando o limite estiver próximo
• Use ambiente virtual Python (venv)
  • Evita conflitos de dependências, isola o ambiente e garante reprodutibilidade por projeto
  • Instalação e execução:

    python3 -m venv venv  
    source venv/bin/activate  
    pip install pytz  
    

  • Para remover, basta apagar a pasta do ambiente virtual para uma desinstalação limpa
• Cadastre um alias personalizado no shell
  • Encurta comandos repetitivos para execução em uma linha

    alias claude-monitor='cd ~/Claude-Code-Usage-Monitor && source venv/bin/activate && ./ccusage_monitor.py'  
    

  • Adicione em .bashrc ou .zshrc para executar o monitor diretamente com um único comando

Melhores práticas de uso

• Monitore constantemente o Burn Rate (taxa de consumo)
  • Fique atento quando o uso de tokens subir de repente
  • Ajuste a intensidade do trabalho conforme o tempo e a quantidade de tokens restantes
  • Reorganize grandes tarefas, como refatorações em larga escala, antes ou depois do reset da sessão (reinicialização dos tokens)
• Agendamento estratégico de sessões
  • Comece tarefas grandes logo após o reset de tokens; quando o limite estiver próximo, faça tarefas mais leves

    ./ccusage_monitor.py --reset-hour 9  
    

  • É possível operar várias sessões sobrepostas usando a regra de 5 horas por sessão
• Defina claramente o fuso horário
  • Reflita o horário real de trabalho/colaboração para prever com precisão o reset de tokens e organizar o cronograma

    ./ccusage_monitor.py --timezone Asia/Seoul  
    

  • Evita diferenças de horário e reduz a confusão sobre o vencimento das sessões ao colaborar com vários países ou equipes

Dicas de otimização

• Configuração do ambiente de terminal
  • Recomenda-se um terminal com largura mínima de 80 caracteres
  • O suporte a cores maximiza o feedback visual
  • Recomenda-se monitoramento contínuo em uma janela dedicada
• Integração ao fluxo de trabalho
  • Use multiplexadores de terminal como tmux para monitorar em paralelo ao desenvolvimento

    tmux new-session -d -s claude-monitor './ccusage_monitor.py'  
    tmux attach -t claude-monitor  
    

• Estratégia com múltiplas sessões
  • Cada sessão permanece fixa em 5 horas, e várias sessões sobrepostas podem ser gerenciadas ao mesmo tempo
  • Distribua tarefas longas entre várias sessões, prestando atenção aos limites e ao vencimento de cada uma

Exemplo de fluxo de trabalho real

• Desenvolvimento de projeto grande

  ./ccusage_monitor.py --plan max20 --reset-hour 8 --timezone America/New_York  
  

  • Reset de tokens às 8h → início do desenvolvimento das funcionalidades principais
  • Às 10h, verificação do Burn Rate e ajuste do ritmo de trabalho
  • Às 12h, revisão e ajuste da programação da tarde
  • Às 14h, abertura de nova sessão para lidar com problemas complexos
  • Às 16h, tarefas leves e preparação para a sessão da noite
• Uso focado em aprendizado/experimentos

  ./ccusage_monitor.py --plan pro  
  

  • Adequado para estudos leves e escrita de código experimental
• Desenvolvimento intenso em sprint

  ./ccusage_monitor.py --plan max20 --reset-hour 6  
  

  • Configuração ajustada para desenvolvimento com expectativa de alto consumo intensivo de tokens

[fanotify]

É a mesma coisa: https://pt.news.hada.io/topic?id=21560

[GN⁺]

Opinião no Hacker News

• Acho frustrante a falta de transparência do Claude, e gostei bastante desta ideia O principal diferencial do Claude Code em relação ao app desktop é conseguir gerenciar melhor contexto e limites, como no modo compact e na exibição da % de capacidade restante, mas ainda parece insuficiente Como sugestão adicional, pessoalmente acho que usar emojis demais no README do projeto passa uma impressão muito pouco profissional, como se fosse um projeto codado só na "vibe" por uma IA sem supervisão adequada

  • Na época em que entrei na área de software, se te pegassem usando emoji no codebase era clima de te mandar para o hospício Hoje os tempos mudaram completamente, e eu uso bastante emoji para organizar contexto visualmente Agora meu código tem emojis o bastante para me deixar feliz

  • Hoje em dia esse estilo com emojis aparece bastante em startups e empresas mais jovens Provavelmente é muita influência do Notion Na nossa empresa, sempre escolhemos emojis até para criar listas, páginas e convites de calendário

  • Acho bem irônico ver esse tipo de comentário em um software feito para programação com IA

  • Na prática, olhando o código, é só um arquivo Python de 400 linhas que basicamente encapsula o ccusage Então dá para entender por que isso passa essa impressão

  • Quando a IA gera descrição de PR ou README, eu sempre coloco no prompt a condição "seja conciso, sem floreios nem emojis" Assim a festa caótica de emojis vira uma documentação adequada Mas isso pode variar conforme o contexto

• Sou o criador do ccusage, e fico feliz que as pessoas estejam usando nosso open source de várias formas Happy vibe coding!

  • Curiosamente, o Show HN do ccusage não teve nenhum comentário, mas esta thread está super movimentada, o que é engraçado Link da thread relacionada

• Só como referência, o limite máximo de tokens que já tive em uma sessão foi de cerca de 337.492, e eu uso o plano Max20 e o Opus em cerca de 99% do tempo Uso o Claude Code desde 27 de maio e, no total, já consumi 1.374.439.311 tokens, o que dá algo em torno de US$ 3.397

  • Com o plano Max20, eu já usei algo em torno de US$ 2.100 Fico me perguntando se sobra uma margem gigantesca na API ou se eles estão operando no prejuízo Eu uso todo dia, mas não acho que use de forma exagerada

  • Você não bate em rate limit com frequência no Opus? E não acha ele lento em comparação com o Sonnet?

• Eu já consigo perceber intuitivamente o quão perto estou do limite de tokens Também percebo quando a própria conversa parece estar chegando no máximo, e aí uso os últimos recursos restantes para gerar um resumo e continuar o trabalho em uma conversa nova Essas ferramentas de IA agora parecem fazer parte do meu relógio biológico Toda quarta-feira o limite semanal do ChatGPT é resetado, então quarta acabou virando um novo domingo para mim

• Observei que o uso de tokens não é resetado se não chegar a 100% mesmo depois que a janela de tempo passa Por exemplo, você usa 90%, entra na próxima janela e consome rapidamente os 10% restantes, aí acaba tendo que esperar bastante tempo

• Eu criei uma ferramenta de UI (crystal) que permite usar várias sessões do Claude Code ao mesmo tempo Como costumo trabalhar em vários recursos em paralelo, frequentemente chego no limite da minha conta Normalmente isso acontece perto do horário de reset, mas seria melhor ainda saber com antecedência quando preciso fazer uma pausa

  • Eu uso Claude Code intensamente, mas não tenho confiança suficiente no meu entendimento de git para montar por conta própria um tooling com worktree e múltiplas sessões Sinceramente, até usar essa ferramenta me dá um pouco de medo; no cenário ideal, eu gostaria de rodar cada worktree em um contêiner, mas parece difícil fazer isso funcionar com a mesma fluidez do Crystal

  • Gosto da ferramenta, mas Crystal já era o nome de uma linguagem de programação que eu usei antes, então isso me confunde

  • Se você abrir uma issue no GitHub (aqui), posso tentar integrar com o meu usage monitor também

  • Muito legal Eu mesmo quase pedi ao Laude para fazer algo assim, não por projeto, mas para 5 projetos simultâneos Concordo que há muitas oportunidades de uso

• Muito interessante, mas será que o limite de tokens do plano Pro é mesmo só 7.000? Ou seja, nem 7.000 palavras seriam, mas na prática parece dar para usar muito mais que isso Se fosse só isso, parece que qualquer conversa um pouco mais longa bateria no limite rapidinho, mas eu nunca esbarrei nele Talvez seja uma limitação que só se aplica ao Claude Code, ainda não usei muito o Claude Code, então não tenho certeza

  • O plano Pro custa US$ 20 por mês. Recentemente passou a dar acesso ao claude code Mas ouvi relatos de que alguns usuários batem no limite com apenas algumas queries Então acho que esse número deve estar certo O limite da interface de chat e o limite do Claude Code são separados

• Excelente demais, obrigado por criar isso Dá para instalar com uv? Compartilharam o link do uv e também um exemplo de comandos de shell com o passo a passo da instalação em uma linha por vez

  • Se esse repositório estivesse estruturado como pacote, com project.toml e afins, daria para instalar mais rápido com pipx (pipx) assim

pipx install git+https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor ccusage_monitor No uv deve existir algo parecido (uvx), mas não sei ao certo se ele tem a mesma função ou propósito do pipx

• Só para constar, praticamente tudo que dá para instalar com pip também dá para instalar com uv, então com uv também deve dar para fazer de forma mais simples

• Fiquei na dúvida se esta ferramenta tem alguma utilidade além de rodar o ccusage chamando o shell Sinceramente, projetos desse tipo me decepcionam um pouco e passam a sensação de que foram feitos de uma tacada só com ferramenta de IA No Show HN nem sequer mencionam que todo o trabalho real é feito por outra ferramenta, o que é uma pena

• Ontem tive uma experiência estranha no Claude Code Ele falhou ao tentar converter uma página de tabela phtml antiga em PHP para um novo layout com div e me fez gastar uns US$ 4 nisso Pode ter sido algum problema com WSL, mas espero que isso não aconteça com frequência

  • O Claude Code tem uma curva de aprendizado considerável É preciso conduzir sessões longas de conversa, discutir bem os requisitos e levar o modelo a fazer perguntas claras Mesmo assim, esse tipo de falha pode acontecer às vezes, então é importante lembrar que é uma ferramenta bem cara Não é magia, como youtubers e blogueiros às vezes fazem parecer