Tokmeter

---

Por quê

Cada agente cobra você separadamente e mostra apenas a própria visão. O Claude Code sabe quanto o Claude Code custou. O Codex sabe quanto o Codex custou. Nada sabe quanto hoje custou, ou qual projeto está queimando mais silenciosamente, ou se o modelo para o qual você mudou é realmente mais barato para o trabalho que você faz.

O Tokmeter responde a isso a partir de dados já presentes no seu disco. Ele analisa os logs de sessão locais de cada agente, precifica-os com um catálogo de modelos atualizado e mantém um registro diário somente de acréscimos, para que o histórico sobreviva mesmo depois que os agentes rotacionam os próprios logs.

npx @sriinnu/tokmeter --today

Como é

CLI — uso por projeto, modelo e provedor	Digest — um boletim semanal

Há também uma interface de terminal (tokmeter-tui), um painel web local, uma linha de status para o Claude Code e um servidor MCP para que um agente possa consultar os próprios gastos.

Instalação

Requer Node.js 18+. Ler arquivos de sessão não exige credenciais de provedor; as consultas de preço buscam um catálogo público, e o --light as ignora completamente.

# Try it without installing
npx @sriinnu/tokmeter --today

# Install the CLI, and the daemon/MCP server
npm install -g @sriinnu/tokmeter @sriinnu/tokmeter-mcp

Pacote	Conteúdo
@sriinnu/tokmeter	API principal, CLI e interface de terminal
@sriinnu/tokmeter-mcp	Servidor MCP, daemon, linha de status e interface de terminal ao vivo

packages/core, packages/cli e packages/tui são pacotes privados do workspace agrupados no @sriinnu/tokmeter. O packages/web é um aplicativo privado separado do workspace, executado a partir do código-fonte.

Claude Code e Codex são os principais alvos de validação. Veja compatibilidade de provedores para os outros analisadores e suas limitações conhecidas.

CLI

tokmeter --today
tokmeter models --project my-app --json
tokmeter daily --week
tokmeter projects
tokmeter stats --month
tokmeter digest --period week
tokmeter pricing sonnet

Os filtros incluem --project, --claude, --codex, --week, --month e --since YYYY-MM-DD --until YYYY-MM-DD. Use --json para saída legível por máquina e --light para relatórios somente de tokens.

• Aliases: mescle nomes de exibição, marque projetos ou oculte-os das listas.
• Backup e restauração: snapshots portáteis, pré-visualização de limpeza, restauração. A limpeza exclui arquivos de origem; mantenha a confirmação e as etapas de backup.
• Referência da CLI: todos os comandos com exemplos.
• Como os números funcionam: o que cada categoria significa e onde entram as estimativas.

API TypeScript

A exportação raiz fornece a API principal. Os auxiliares de consulta de conveniência usam o subcaminho /cli.

import { TokmeterCore } from "@sriinnu/tokmeter";
import { loadTokmeterSummary } from "@sriinnu/tokmeter/cli";

const core = new TokmeterCore();
await core.scan({ providers: ["codex", "claude-code"], today: true });
const models = core.getModelCosts();
const daily = core.getDailyBreakdown();

const summary = await loadTokmeterSummary({ week: true, light: true });

Reutilize uma única varredura principal ao consultar vários detalhamentos. Veja orientações de integração, uso da API principal e SKILL.md para instruções de integração voltadas a agentes.

Daemon, MCP e linha de status

tokmeter-mcp daemon start
tokmeter-mcp daemon status
tokmeter-mcp serve             # MCP server over stdio
tokmeter-mcp statusline        # one statusline tick
tokmeter-mcp live              # live terminal UI

O daemon usa a porta HTTP local 9877 para consultas e a porta WebSocket 9876 para registro ao vivo. O aplicativo macOS, a linha de status e o servidor MCP consomem o estado compartilhado dele. Os comandos do daemon pertencem ao @sriinnu/tokmeter-mcp; instale-o para essas superfícies.

As ferramentas MCP usam o prefixo tokmeter_ e cobrem consultas de uso, comparações, previsões, exportação e operações confirmadas de limpeza/restauração. Veja a referência MCP para nomes, configuração e exportações programáticas.

O tokmeter-mcp editors lista os alvos do instalador. O tokmeter-mcp install-mcp e o tokmeter-mcp install-statusline gravam a configuração do editor; inspecione as configurações geradas para o seu editor. Veja arquitetura para detalhes de registro, autenticação, atualização, armazenamento e ciclo de vida do daemon.

Interfaces de terminal e web

# After installing @sriinnu/tokmeter
tokmeter-tui

# Without a global install
npx -p @sriinnu/tokmeter tokmeter-tui

A interface de terminal oferece visualizações de visão geral, modelo, diária e estatísticas. Veja as teclas e comandos dela.

Execute o workspace web a partir de um checkout do código-fonte:

bun install
bun run dev:web

Abra http://localhost:3000. Veja configuração web e fontes de dados.

Aplicativo macOS

As versões de lançamento têm como alvo Apple silicon e macOS 14+. Node.js 18+ com npx também é necessário para o daemon local.

Instale o @sriinnu/tokmeter-mcp, execute o tokmeter-mcp daemon start e abra o TokmeterBar a partir do /Applications. Baixe o aplicativo em GitHub Releases.

O pop-up dá destaque igual aos tokens de hoje e ao custo estimado da API, com modelos e projetos abaixo. Os cartões de gráfico ao passar o mouse mostram tokens e custos diários exatos. Usage details expande totais vitalícios, tendências e sinais. Seis temas são selecionáveis: Terminal, Paper, Prism, Lagoon, Carbon e Glass. O Hub fornece detalhamentos maiores e configurações. Configurações → Open web dashboard inicia o servidor local sob demanda; Stop web dashboard ou sair do aplicativo o interrompe.

Veja detalhes de build e execução no macOS, verificações de primeiro uso e validação do popover. O rastreador de conclusão registra as portas restantes de máquina nova, confiabilidade, atualização, contabilidade, acessibilidade e avaliação.

O passo a passo sintético documenta como as imagens de exemplo foram geradas; não é uma captura de um candidato local atual.

Licença

AGPL-3.0-only. Veja notas de licenciamento para saber o que isso significa se você incorporar o Tokmeter em outro produto.