Como economizar tokens no Claude Code com o Token Dashboard do Nate

Se você já trabalha com o Claude Code, sabe que cada chamada consome tokens e, consequentemente, afeta o seu plano de uso ou a fatura da API. Porém, nem sempre é evidente onde esses tokens estão sendo gastos. Foi pensando nisso que o desenvolvedor Nateherkai criou o Token Dashboard, uma ferramenta local que transforma os arquivos JSONL gerados pelo Claude Code em análises claras de consumo, permitindo que você veja exatamente onde está ocorrendo o desperdício.

O que é o Token Dashboard?

O Token Dashboard é um projeto open‑source escrito em Python (stdlib only) que lê os arquivos .jsonl armazenados em ~/.claude/projects/ e os converte em um banco SQLite local. A partir desse banco, uma interface web (servida em http://127.0.0.1:8080) exibe várias abas com métricas detalhadas:

• Overview: visão geral de tokens de entrada, saída e cache, custo estimado, gráficos diários e por projeto.
• Prompts: lista dos prompts mais caros, permitindo clicar para ver a resposta do assistente, as ferramentas chamadas e o tamanho de cada resultado.
• Sessions: visualização turno a turno de uma sessão específica, com tokens por turno e chamadas de ferramenta.
• Projects: comparação entre projetos, mostrando quais arquivos foram mais acessados.
• Skills: frequência de uso de cada skill e, quando possível, o custo em tokens.
• Tips: sugestões baseadas em regras para reduzir o consumo (leituras repetidas de arquivos, resultados de ferramentas muito grandes, baixa taxa de cache hit, etc.).
• Settings: troca entre os planos API, Pro, Max ou Max‑20x para que os valores de custo reflitam exatamente o seu contrato.

Tudo isso ocorre localmente: nenhum dado deixa sua máquina, não há telemetria nem chamadas externas. O dashboard apenas lê os arquivos já existentes e mantém um cache em ~/.claude/token-dashboard.db.

Como instalar e colocar em funcionamento

1. Clone o repositório:

   git clone https://github.com/nateherkai/token-dashboard.git
   cd token-dashboard

2. Certifique‑se de ter o Python 3.8+ instalado (macOS e a maioria das distribuições Linux já vêm com ele; no Windows, use winget install Python.Python.3.12 ou baixe de python.org).
3. Execute o Claude Code ao menos uma vez para que ele gere os arquivos JSONL.
4. Inicie o dashboard:

   python3 cli.py dashboard

   O comando faz um escaneamento inicial (pode levar de 20 a 60 segundos em máquinas com bastante uso), sobe um servidor local em http://127.0.0.1:8080 e abre o navegador padrão.

5. Para usar apenas o cache (pular o escaneamento): python3 cli.py dashboard --no-scan.
6. Para mudar a porta, defina a variável de ambiente PORT antes de rodar, por exemplo: PORT=9000 python3 cli.py dashboard.

Principais insights que você pode obter

Identificando prompts caros

Na aba Prompts você vê uma lista ordenada pelo número de tokens consumidos. Clicando em qualquer linha, o dashboard mostra:

• O prompt completo que você enviou.
• A resposta do assistente (com os trechos que foram armazenados em cache, se houver).
• Cada chamada de ferramenta feita pelo agente, com o tamanho do retorno em tokens.

Esse nível de detalhe permite responder à pergunta “por que esse prompt foi tão caro?” – exatamente o ponto que Nate costuma enfatizar em seus vídeos: entender o porquê antes de aplicar qualquer técnica de otimização.

Detectando padrões de desperdício

A aba Tips gera sugestões automáticas baseadas em regras simples, tais como:

• Leitura repetida do mesmo arquivo em uma sessão (ex.: ler config.json 20 vezes).
• Resultados de ferramentas que retornam blocos de texto excessivamente grandes (por exemplo, um grep que devolve 80 k tokens).
• Baixa taxa de cache hit, indicando que você está reprocessando o mesmo conteúdo inúmeras vezes.

Cada sugestão vem com uma breve explicação e, muitas vezes, um link direto para o prompt ou sessão onde o problema ocorreu, facilitando a correção.

Comparando projetos e skills

Se você trabalha em múltiplos repositórios ou experimenta diferentes abordagens, a aba Projects mostra o consumo total por projeto, permitindo identificar quais códigos são mais “gulosos” em tokens. Já a aba Skills revela quais habilidades (por exemplo, web_search, file_read, code_edit) você invoca com mais frequência e quanto cada uma custa em média. Essa visão ajuda a decidir se vale a pena criar uma skill personalizada ou reutilizar um trecho de código já em cache.

Dicas práticas para economizar tokens no dia a dia

• Revise os prompts mais caros: use a aba Prompts para identificar os top 5 e tente reescrevê‑los de forma mais direta, removendo contexto desnecessário.
• Aproveite o cache: sempre que possível, peça ao Claude Code para reutilizar resultados anteriores (por exemplo, ao pedir múltiplas edições no mesmo arquivo, mantenha o contexto em vez de solicitar leituras novas).
• Limite o tamanho das saídas de ferramentas: ao usar grep, ls ou comandos similares, adicione filtros que reduzam o volume de dados retornados.
• Monitore a taxa de cache hit: a aba Overview mostra essa métrica; valores abaixo de 30 % indicam grande oportunidade de melhoria.
• Ajuste o plano nas Settings: se você está no plano Pro ou Max, verifique se o dashboard está calculando o custo com a tabela correta; isso evita surpresas na fatura.

Como Nate costuma dizer: “Não adianta sair aplicando qualquer técnica sem entender como você está usando o Claude Code.” O Token Dashboard é exatamente o espelho que revela esse uso.

Conclusão

O Token Dashboard do Nateherkai transforma os dados brutos do Claude Code em informações acionáveis, permitindo que você veja, entenda e aja sobre o consumo de tokens. Ao instalar essa ferramenta local, você ganha controle total sobre seus custos, melhora a produtividade e ainda aprende a escrever prompts mais eficientes – tudo sem sair da sua máquina ou compartilhar dados com terceiros.

Pronto para colocar em prática? Clone o repositório, rode o dashboard e descubra onde seus tokens estão sendo queimados. Depois, compartilhe nos comentários qual foi a maior economia que você conseguiu alcançar!