vole

Vole é um monitor de uso, custo e anomalias local-first para agentes de codificação de IA. Ele foca em cenários onde vários agentes operam simultaneamente, consumindo tokens de forma independente e sem sinalizar falhas — como loops de ferramentas, tentativas contra APIs quebradas ou releituras repetitivas de contextos extensos. Enquanto outras ferramentas respondem "quanto eu gastei?", o Vole pergunta "algo está dando errado agora?" e reporta os gastos como um efeito colateral. Manipulação de Dados Vole lê os arquivos de log que as ferramentas já gravam no disco — por exemplo, ~/.claude/projects/**/*.jsonl para Claude Code, ~/.local/share/opencode/opencode.db para OpenCode, ~/.codex/sessions/**/rollout-*.jsonl para Codex CLI, ~/.grok/logs/unified.jsonl para Grok CLI, além de armazenamentos locais para Cursor, Devin e Antigravity — e os normaliza em um único esquema. Tudo é executado localmente: sem scraping, sem APIs de nuvem, sem login, e nenhum conteúdo de prompt ou ferramenta é armazenado. A única permissão opcional solicitada é a de notificações, para alertas de incidentes críticos. Ferramentas Suportadas e Política de Fidelidade A cobertura varia por ferramenta: Claude Code e OpenCode fornecem tokens e custos exatos; Codex CLI e Grok CLI fornecem tokens exatos, mas não possuem tarifas publicadas; Cursor, Devin e Antigravity não registram tokens localmente e, portanto, são cobertos apenas como atividade. O projeto estabelece que não existe um nível de "estimativa" por política — a contagem de tokens é lida literalmente dos logs da ferramenta ou é genuinamente ausente, e linhas sem tokens ainda contam como chamadas, mas são excluídas dos agregados de tokens e custos. A estimativa de tokens do Cursor com base em linhas de código foi considerada e explicitamente rejeitada. O Aplicativo Um item na barra de menus mostra tokens em tempo real, custo ou apenas o ícone, que muda de cor quando um incidente está aberto. Ao clicar, abre-se um painel com números principais, um sparkline e barras por ferramenta; um dashboard fornece a visão completa. Seu elemento assinatura é uma linha do tempo anotada com incidentes que empilha tokens por ferramenta e nomeia o bucket, seus tokens e quaisquer incidentes disparados ao passar o mouse. O app incorpora seu próprio coletor, inicia-o e atualiza-se no local: um lançamento com arquivo checksummed oferece instalação em um clique que verifica o SHA-256 publicado antes de trocar o bundle, e lançamentos sem checksum nunca instalam silenciosamente. Linha de Comando e MCP Além do app, o Vole expõe comandos de terminal sobre os mesmos dados: pnpm top (sessões ao vivo, contexto versus janela, tokens por minuto, contagem regressiva de cache), pnpm digest (resumo de uso do agente em markdown com opções de intervalo e JSON), pnpm pr (uso no branch atual para descrição de PR), pnpm statusline e pnpm mcp, um servidor MCP stdio. O servidor MCP expõe vole_summary, vole_live_sessions, vole_session, vole_incidents, vole_breakdown, vole_whatif e vole_digest, permitindo que um agente pergunte quanto sua própria sessão custou ou se o Vole a sinalizou. O servidor lê o banco de dados local e responde via stdout. Regras de Anomalia Cinco regras são integradas: billable_burn_spike (janela de 10 minutos custando mais de 3x a janela típica daquela sessão), repeat_call_loop (45+ chamadas em 5 minutos enquanto a saída permanece estável), error_storm (taxa de erro acima de 20% em 15 minutos com pelo menos 5 erros), rate_limit_pressure (Codex reporta mais de 80% da quota consumida) e context_pressure (uma chamada ocupou pelo menos 80% da janela de contexto do modelo). As linhas de base são leave-one-out, comparando uma janela com a mediana de todas as outras, e a detecção de loop requer dois sinais para que um surto produtivo de chamadas não seja confundido com um loop. Modelo de Custo O custo é o valor equivalente da API ao preço de tabela — o que o uso teria custado via API — e a interface observa que planos de assinatura não são cobrados por token. As tarifas ficam em packages/core/src/data/pricing.json, versionadas com effective_from, e um arquivo ~/.vole/pricing.json por instalação sobrepõe esses valores para que um modelo possa ser adicionado sem um novo lançamento; linhas armazenadas antes de um modelo ter uma tarifa são precificadas retroativamente. Modelos desconhecidos retornam NULL, nunca 0. Verificação e Testes O projeto fornece pnpm test para testes unitários de regras, consultas, bucketing e invariantes de confiança, e pnpm verify, que reconcilia cada linha armazenada com seu registro de origem usando uma fórmula de custo reimplementada independentemente. A verificação compara por registro em vez de por total e falha em um armazenamento vazio para evitar passagens vacuamente positivas. Um comando pnpm seed escreve 30 dias de histórico sintético marcado como source='seed', mapeado separadamente dos dados reais. Construção e Limitações Construir a partir do código-fonte requer Node 22+, pnpm e Xcode 26, testado no macOS 26 arm64; pnpm app:bundle constrói e abre o app, ou o coletor e o app podem ser executados separadamente. Limitações documentadas incluem cobertura rasa para ferramentas que não registram tokens locais, is_error cobrindo apenas erros de API (fazendo com que error_storm possa subcontar), velocidades de geração sendo limites inferiores para algumas ferramentas, janelas de contexto resolvendo apenas para IDs de modelos first-party e temporização aproximada para Antigravity baseada em mtimes de arquivos. O projeto possui licença MIT e aceita contribuições, com duas regras de revisão: nunca inventar um número e cada coletor deve ser idempotente.