Monitoramento de Custos

O que Monitoramento de Custos faz?

Use esta skill para analisar o histórico de custos e uso do Claude Code a partir do log de métricas escrito pelo hook stop:cost-tracker do ECC.

Onde os dados estão

O tracker adiciona um objeto JSON por sessão encerrada em ~/.claude/metrics/costs.jsonl. Cada linha é um snapshot cumulativo daquela sessão, portanto, para obter o gasto total, pegue a linha mais recente por session_id e some entre sessões — somar todas as linhas resulta em contagem múltipla.

Esquema das linhas:

Campo	Significado
timestamp	Timestamp ISO do snapshot
session_id	Identificador da sessão do Claude Code
transcript_path	Caminho para o transcript da sessão
model	Modelo utilizado
input_tokens / output_tokens	Contagens de tokens
cache_write_tokens / cache_read_tokens	Contagens de tokens de cache de prompt
estimated_cost_usd	Custo cumulativo pré-calculado em USD para a sessão

Prefira estimated_cost_usd em vez de calcular manualmente — os preços de modelo e cache mudam, e o tracker é a fonte verdadeira.

Quando usar

• O usuário pergunta "quanto eu já gastei?", "quanto custou esta sessão?" ou "qual é o meu uso de tokens?"
• O usuário menciona orçamentos, limites de gastos, estouros ou controles de custo.
• O usuário deseja um detalhamento de custos por modelo, sessão ou data, ou uma exportação CSV.

Como funciona

Primeiro, verifique se o log existe (use node, não sqlite3 — o tracker escreve JSONL, e node é multiplataforma):

node -e 'const fs=require("fs"),os=require("os"),p=require("path");const f=p.join(os.homedir(),".claude","metrics","costs.jsonl");console.log(fs.existsSync(f)?"log de custos encontrado":"log de custos não encontrado: "+f)'

Se o log estiver faltando, não invente dados de uso. Informe ao usuário que o monitoramento de custos é populado após o término da primeira sessão com o hook stop:cost-tracker habilitado.

Exemplo — resumo, por modelo, últimos 7 dias

node -e '
const fs=require("fs"),os=require("os"),path=require("path");
const f=path.join(os.homedir(),".claude","metrics","costs.jsonl");
if(!fs.existsSync(f)){console.log("log de custos não encontrado: "+f);process.exit(0);}
const rows=fs.readFileSync(f,"utf8").split(/\r?\n/).filter(Boolean).map(l=>{try{return JSON.parse(l)}catch{return null}}).filter(Boolean);
const bySession=new Map();
for(const r of rows){const k=r.session_id||r.transcript_path||r.timestamp;const p=bySession.get(k);if(!p||String(r.timestamp)>String(p.timestamp))bySession.set(k,r);}
const latest=[...bySession.values()];
const cost=r=>Number(r.estimated_cost_usd)||0, day=r=>String(r.timestamp||"").slice(0,10), sum=a=>a.reduce((s,r)=>s+cost(r),0), f4=n=>"$"+n.toFixed(4);
const today=new Date().toISOString().slice(0,10), yest=new Date(Date.now()-864e5).toISOString().slice(0,10);
console.log("hoje: "+f4(sum(latest.filter(r=>day(r)===today)))+" | ontem: "+f4(sum(latest.filter(r=>day(r)===yest)))+" | total: "+f4(sum(latest))+" ("+latest.length+" sessões)");
const m=new Map();for(const r of latest){const k=r.model||"(desconhecido)";m.set(k,(m.get(k)||0)+cost(r));}
console.log("por modelo:");[...m.entries()].sort((a,b)=>b[1]-a[1]).forEach(([k,v])=>console.log("  "+f4(v)+"  "+k));
'

Para um detalhamento de sessão ou exportação CSV, itere sobre o mesmo conjunto latest (ou as linhas brutas para CSV) e imprima os campos necessários.

Diretrizes de relato

Ao apresentar dados de custo, inclua o gasto de hoje vs ontem, total geral entre todas as sessões, um detalhamento por modelo e contagem de sessões. Formate valores abaixo de um dólar com quatro casas decimais, valores maiores com duas.

Padrões antagônicos

• Não some todas as linhas — elas são cumulativas por sessão; reduza para a última linha por session_id primeiro.
• Não estime custos a partir de contagens brutas de tokens quando estimated_cost_usd estiver presente.
• Não assuma que o log existe sem verificar.
• Não codifique preços atuais de modelo em respostas visíveis ao usuário.
• Não recomende instalar hooks ou plugins não revisados que executem código arbitrário.

Relacionados

• /cost-report — Relato em formato de comando sobre o mesmo log de métricas.
• cost-aware-llm-pipeline — Padrões de roteamento de modelo e design de orçamento.
• token-budget-advisor — Planejamento de contexto e orçamento de tokens.
• strategic-compact — Compactação de contexto para reduzir gastos repetidos com tokens.