3 Ferramentas Open Source para Monitorar Uso de Claude Code

Para os Vibe Coders, ferramentas como o Claude Code da Anthropic tornaram-se indispensáveis para muitos engenheiros. Desde a geração de código boilerplate até a depuração de algoritmos complexos, o Claude Code pode aumentar significativamente a produtividade. No entanto, esse poder vem com a necessidade de supervisão. O uso não monitorado pode levar a custos inesperados, gargalos de desempenho e uma compreensão incompleta de como essas ferramentas poderosas estão impactando seu ciclo de vida de desenvolvimento.

O monitoramento eficaz não se trata apenas de rastrear despesas; trata-se de entender o valor. Você está usando os modelos mais econômicos para suas tarefas? Existem padrões em seu fluxo de trabalho que poderiam ser otimizados? Como a assistência de IA está se traduzindo em ganhos tangíveis de produtividade para sua equipe? Responder a essas perguntas requer dados, e é aí que as ferramentas de monitoramento de código aberto entram em jogo.

Embora o Claude Code forneça algum nível de informação de uso, um ecossistema dedicado de ferramentas de código aberto surgiu para oferecer insights mais profundos e acionáveis. Essas ferramentas atendem a uma variedade de necessidades, desde o desenvolvedor individual que deseja uma verificação rápida de seu consumo diário de tokens até a equipe empresarial que busca construir uma plataforma de observabilidade abrangente em torno de seu uso de IA.

Neste artigo, faremos uma análise aprofundada de três ferramentas de código aberto distintas que o ajudam a monitorar o uso do seu Claude Code:

1. ccusage: Uma interface de linha de comando (CLI) rápida e simples para análise rápida e ad-hoc dos seus dados de uso local.
2. Claude-Code-Usage-Monitor: Um painel de terminal interativo e em tempo real que o ajuda a manter-se atualizado sobre sua sessão atual e evitar atingir os limites de tokens.
3. claude-code-otel: Uma pilha de observabilidade completa, de nível empresarial, para monitoramento abrangente e de longo prazo do uso, desempenho e custos de toda a equipe.

Exploraremos a arquitetura, os recursos e os casos de uso ideais para cada um, ajudando você a escolher a ferramenta certa para dominar seu fluxo de trabalho de desenvolvimento com o Claude Code.

ccusage

Para desenvolvedores que valorizam velocidade, simplicidade e eficiência, o ccusage é a ferramenta perfeita. Criado pelo usuário do GitHub ryoppippi, é uma ferramenta CLI leve e incrivelmente rápida que fornece relatórios claros e concisos sobre o uso e os custos do seu Claude Code, analisando os arquivos de log JSONL locais que o Claude Code gera.

Principais Recursos:

• Múltiplas Visualizações de Relatório: Obtenha insights adaptados às suas perguntas com relatórios diários, mensais, de sessão e de blocos (que se alinham com as janelas de faturamento de 5 horas do Claude Code).
• Monitoramento ao Vivo: Com o comando ccusage blocks --live, você pode obter um painel em tempo real que mostra o progresso da sua sessão ativa, a "taxa de queima" de tokens e os custos projetados.
• Análise de Custo e Modelo: A ferramenta não apenas conta tokens; ela os traduz para USD e pode detalhar os custos pelos modelos específicos que você usou (Opus, Sonnet, Haiku, etc.).
• Saída Flexível: Embora suas tabelas padrão legíveis por humanos sejam lindamente formatadas e até se adaptem à largura do seu terminal, você também pode exportar qualquer relatório para JSON com a flag --json para fácil integração em outros scripts ou ferramentas.
• Execução sem Dependências: Usando npx, você pode executar o ccusage instantaneamente sem uma instalação permanente, tornando-o ideal para verificações rápidas e pontuais.

Como Funciona:

ccusage é uma ferramenta baseada em NodeJS escrita em TypeScript. Sua mágica reside em sua simplicidade. Ela analisa diretamente os arquivos .jsonl armazenados no seu diretório de configuração local do Claude Code (por exemplo, ~/.config/claude/logs/). Ela lê esses logs de eventos, agrega as contagens de tokens para prompts e respostas, aplica informações de preços atualizadas para cada modelo e apresenta os dados em um formato tabular limpo. Essa abordagem local significa que é incrivelmente rápida e funciona totalmente offline (desde que tenha armazenado em cache os dados de preços uma vez).

Instalação e Uso:

Começar com o ccusage não poderia ser mais fácil. Para uma execução direta, sem instalação, basta usar:

npx ccusage@latest

Este comando buscará a versão mais recente e mostrará um relatório diário. Para visualizações mais detalhadas, você pode especificar o tipo de relatório:

# Veja um resumo do uso para cada mês
npx ccusage@latest monthly

# Agrupe o uso por sessões de conversação
npx ccusage@latest session --breakdown

# Monitore o bloco de faturamento atual de 5 horas em tempo real
npx ccusage@latest blocks --live

Para quem é?

ccusage é a ferramenta ideal para o desenvolvedor individual. É perfeita para:

• Responder à pergunta: "Quanto gastei no Claude Code ontem?"
• Verificar o uso de tokens no final de uma longa sessão de codificação.
• Realizar análises simples e ad-hoc sem a sobrecarga de uma configuração complexa.
• Direcionar dados de uso para outros scripts via sua saída JSON.

Se você precisa de uma maneira rápida e sem complicações para controlar seu uso pessoal do Claude Code, o ccusage é um excelente ponto de partida.

Claude-Code-Usage-Monitor

Enquanto o ccusage se destaca na análise post-hoc, o Claude-Code-Usage-Monitor de Maciek-roboblog foi projetado para ser seu companheiro ao vivo durante suas sessões de codificação. Esta ferramenta baseada em Python fornece um painel de terminal persistente e em tempo real que não apenas mostra o que você usou, mas também prevê o que você vai usar, ajudando-o a evitar atingir inesperadamente seus limites de tokens.

Principais Recursos:

• Painel Interativo em Tempo Real: O monitor fornece uma visualização constantemente atualizada (a cada 3 segundos) do seu uso de tokens dentro da janela de sessão atual de 5 horas.
• Análise Preditiva: Sua característica de destaque é o cálculo da "taxa de queima". Ele analisa seu uso recente para prever quando você poderá esgotar seus tokens para a sessão, dando-lhe a chance de desacelerar.
• Barras de Progresso Visuais: A interface do usuário é rica e intuitiva, com barras de progresso codificadas por cores tanto para o seu consumo de tokens quanto para o tempo restante em sua sessão.
• Ciente de Plano e Fuso Horário: Você pode configurar o monitor para diferentes planos do Claude Code (Pro, Max5, Max20) e definir seu fuso horário local para previsões precisas de reinício de sessão. Ele pode até mesmo detectar automaticamente seu plano com base no uso anterior.
• Sistema de Aviso: A ferramenta o alerta ativamente quando você está se aproximando do seu limite de tokens, ajudando-o a gerenciar seu uso de forma mais proativa.

Como Funciona:

Semelhante ao ccusage, esta ferramenta também monitora os arquivos de log locais do Claude Code. No entanto, em vez de apenas relatar dados passados, ela mantém um estado ao vivo de sua sessão atual de 5 horas. Ela entende o sistema de janela deslizante do Claude Code e calcula seu uso de tokens e taxa de queima dentro desse contexto. É escrita em Python e usa a biblioteca rich para criar sua interface de terminal polida e interativa.

Instalação e Uso:

A maneira recomendada de instalar o Claude-Code-Usage-Monitor é usando uv, um instalador de pacotes Python moderno que lida com ambientes virtuais automaticamente.

# Instale o uv (se você não tiver)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Instale a ferramenta
uv tool install claude-monitor

# Execute o monitor
claude-monitor

Uma vez em execução, ele assumirá sua janela de terminal e exibirá o painel ao vivo. Você pode personalizá-lo com várias flags:

# Especifique seu plano e fuso horário
claude-monitor --plan max20 --timezone America/New_York

Para quem é?

Claude-Code-Usage-Monitor é para o desenvolvedor que deseja se manter continuamente informado durante seu trabalho. É perfeito para:

• Usuários do nível gratuito ou "Pro" que têm limites de tokens mais rigorosos e precisam gerenciá-los com cuidado.
• Desenvolvedores engajados em sessões de codificação longas e intensivas que desejam controlar seu uso.
• Qualquer pessoa que queira evitar a experiência abrupta de ser interrompido no meio de um pensamento por ter atingido um limite.
• Aprendizes visuais que preferem um painel gráfico em vez de relatórios estáticos.

Se você quer uma ferramenta que atua como um "anjo da guarda" para o seu orçamento de tokens, vigiando você e mantendo-o no caminho certo, esta é a ideal para você.

claude-code-otel

As duas primeiras ferramentas são fantásticas para desenvolvedores individuais, mas e se você precisar monitorar o uso do Claude Code em toda uma equipe ou organização? É aqui que o claude-code-otel de ColeMurray se destaca. Não é apenas uma ferramenta; é uma solução de observabilidade completa e auto-hospedada, construída sobre componentes de código aberto padrão da indústria.

Principais Recursos:

• Pilha de Observabilidade Completa: Ele fornece uma configuração pré-configurada de OpenTelemetry, Prometheus, Loki e Grafana, as mesmas ferramentas robustas usadas para monitorar a infraestrutura de produção.
• Dashboards Abrangentes: O projeto vem com dashboards Grafana pré-construídos para análise aprofundada de custo, atividade do usuário, desempenho da ferramenta, métricas de produtividade (como linhas de código alteradas), latência de API, erros e muito mais.
• Monitoramento em Toda a Equipe: Ele é projetado desde o início para agregar dados de múltiplos usuários, permitindo que você veja tendências, identifique usuários avançados e gerencie custos em nível de equipe ou projeto.
• Soberania e Segurança dos Dados: Como você hospeda toda a pilha, todos os seus dados de uso, incluindo prompts de usuário potencialmente sensíveis (se você optar por registrá-los), permanecem dentro de sua própria infraestrutura.
• Baseado em Padrões: Ao usar o OpenTelemetry, ele adere a um padrão neutro em relação a fornecedores para dados de telemetria, tornando-o extensível e à prova de futuro.

Como Funciona:

Esta solução adota uma abordagem fundamentalmente diferente. Ela aproveita o suporte integrado do Claude Code para OpenTelemetry (OTel). Ao definir algumas variáveis de ambiente, você pode configurar a CLI do Claude Code para emitir métricas e logs detalhados. O claude-code-otel fornece uma configuração docker-compose que levanta todo o backend para receber e processar esses dados:

1. OpenTelemetry Collector: Recebe os dados de telemetria de todas as instâncias do Claude Code dos usuários.
2. Prometheus: Coleta e armazena as métricas (por exemplo, contagens de tokens, custos, latência).
3. Loki: Ingesta e armazena os logs de eventos (por exemplo, prompts de usuário, resultados de ferramentas, erros de API).
4. Grafana: Consulta Prometheus e Loki para visualizar os dados em dashboards poderosos e interativos.

Instalação e Uso:

Configurar o claude-code-otel é mais complexo do que as outras ferramentas, mas é notavelmente simplificado graças ao Docker.

1. Clone o repositório:

git clone https://github.com/ColeMurray/claude-code-otel.git
cd claude-code-otel

2. Inicie a pilha:

make up

3. Configure seu ambiente local do Claude Code para enviar dados para sua nova pilha, definindo variáveis de ambiente:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
# ... e algumas outras

4. Acesse seus dashboards navegando para http://localhost:3000 em seu navegador.

Para quem é?

claude-code-otel é a solução definitiva para equipes de engenharia, equipes de plataforma e gerência. É ideal para:

• Organizações que buscam medir o ROI de suas ferramentas de desenvolvimento de IA.
• Líderes de equipe que precisam gerenciar um orçamento compartilhado para o uso do Claude Code.
• Engenheiros de plataforma que precisam monitorar o desempenho e a confiabilidade das ferramentas de IA.
• Qualquer organização que exija uma maneira centralizada, segura e poderosa de entender como a IA está sendo usada em suas equipes de desenvolvimento.

Conclusão: Escolhendo Sua Lente

A jornada para dominar o uso do seu Claude Code começa com visibilidade. As três ferramentas que exploramos oferecem diferentes lentes através das quais você pode ver sua interação com este poderoso assistente de IA.

• Comece com o ccusage para uma maneira simples, poderosa e rápida de obter respostas para perguntas comuns sobre seu uso passado.
• Progrida para o Claude-Code-Usage-Monitor quando quiser passar da análise reativa para o gerenciamento proativo e em tempo real do seu orçamento de tokens durante suas sessões de codificação.
• Adote o claude-code-otel quando seu foco mudar do uso individual para a observabilidade em toda a equipe, gerenciamento de custos e análise de desempenho.

Cada um desses projetos de código aberto representa uma contribuição fantástica para a comunidade de desenvolvedores, capacitando os usuários a passarem de consumidores passivos da tecnologia de IA para participantes ativos e informados. Ao escolher a ferramenta certa para suas necessidades, você pode desbloquear um novo nível de controle e insight, garantindo que você esteja obtendo o máximo valor do seu fluxo de trabalho de desenvolvimento assistido por IA.