Lar

Skill

Produtividade e fluxo de trabalho

cost-tracking

affaan-m/ECC

Analise o uso de tokens, os gastos e os orçamentos do Claude Code a partir do log de métricas do rastreador de custos ECC local. Oferece resumos, detalhamentos por modelo, sessão ou data e exportação para CSV.

...Expandir tudo

Tempo atualizado 2 de Outubro de 2026

# ecc # Claude Code # metrics # jsonl # cost tracking # budget # token usage

Acompanhamento de custos

Use essa habilidade para analisar o histórico de custos e uso do Claude Code a partir do log de métricas que o hook `stop:cost-tracker` do ECC grava.

Onde os dados ficam

O rastreador acrescenta um objeto JSON por encerramento de sessão ao arquivo ~/.claude/metrics/costs.jsonl. Cada linha é um instantâneo acumulado dessa sessão; portanto, para calcular o gasto total, use a linha mais recente por session_id e some entre as sessões — somar todas as linhas resulta em contagem múltipla.

Esquema da linha:

Campo	Significado
`timestamp`	Carimbo de data/hora ISO do instantâneo
`session_id`	Claude Code: identificador da sessão
`transcript_path`	Caminho para a transcrição da sessão
`modelo`	Modelo utilizado
`token_de_entrada` / `token_de_saída`	Contagem de tokens
`cache_write_tokens` / `cache_read_tokens`	Contagem de tokens no cache de prompts
`estimated_cost_usd`	Custo acumulado pré-calculado em USD para a sessão

Prefira usar o `estimated_cost_usd` em vez de calcular manualmente os preços — os preços do modelo e do cache mudam, e o rastreador é a fonte de referência.

Quando usar

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

Como funciona

Primeiro, verifique se o log existe (use o `node`, não o `sqlite3` — o rastreador grava em `JSONL`, e o `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 registro estiver faltando, não invente dados de uso. Informe ao usuário que o rastreamento de custos é preenchido após o término da primeira sessão com o hook `stop:cost-tracker` ativado.

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("registro de custo 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 uma análise detalhada da sessão ou exportação para CSV, percorra o mesmo conjunto mais recente (ou as linhas brutas para CSV) e imprima os campos necessários.

Orientações para relatórios

Ao apresentar dados de custo, inclua os gastos de hoje em comparação com os de ontem, o total de todas as sessões, uma divisão por modelo e a contagem de sessões. Formate valores inferiores a um dólar com quatro casas decimais e valores maiores com duas.

Antipadrões

Não some todas as linhas — elas são cumulativas por sessão; reduza primeiro à linha mais recente por session_id.
Não estime custos a partir de contagens brutas de tokens quando o `estimated_cost_usd` estiver presente.
Não presuma que o log existe sem verificar.
Não codifique manualmente os preços atuais dos modelos nas respostas apresentadas ao usuário.
Não recomende a instalação de hooks ou plugins não revisados que executem código arbitrário.

Relacionado

/cost-report — Relatório em formato de comando sobre o mesmo log de métricas.
cost-aware-llm-pipeline - Padrões de roteamento de modelos e de projeto de orçamento.
token-budget-advisor - Planejamento de contexto e orçamento de tokens.
strategic-compact - Compactação de contexto para reduzir o gasto repetido de tokens.

Ver no GitHub

---
name: cost-tracking
description: Analyze Claude Code token usage, spending, and budgets from the local ECC cost-tracker metrics log. Provides summaries, breakdowns by model, session, or date, and CSV export.
---

# Cost Tracking

Use this skill to analyze Claude Code cost and usage history from the metrics log
that ECC's `stop:cost-tracker` hook writes.

## Where the data lives

The tracker appends one JSON object per session-stop to
`~/.claude/metrics/costs.jsonl`. Each row is a **cumulative snapshot for that
session**, so to total spend you take the **latest row per `session_id`** and
sum across sessions — summing every row multiply-counts.

Row schema:

| Field | Meaning |
| --- | --- |
| `timestamp` | ISO timestamp of the snapshot |
| `session_id` | Claude Code session identifier |
| `transcript_path` | Path to the session transcript |
| `model` | Model used |
| `input_tokens` / `output_tokens` | Token counts |
| `cache_write_tokens` / `cache_read_tokens` | Prompt-cache token counts |
| `estimated_cost_usd` | Precomputed cumulative cost in USD for the session |

Prefer `estimated_cost_usd` over hand-calculating pricing — model and cache
prices change, and the tracker is the source of truth.

## When to Use

- The user asks "how much have I spent?", "what did this session cost?", or
  "what is my token usage?"
- The user mentions budgets, spending limits, overruns, or cost controls.
- The user wants a cost breakdown by model, session, or date, or a CSV export.

## How It Works

First verify the log exists (use `node`, not `sqlite3` — the tracker writes
JSONL, and `node` is cross-platform):

```bash
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)?"cost log found":"cost log not found: "+f)'
```

If the log is missing, do not fabricate usage data. Tell the user that cost
tracking populates after the first session ends with the `stop:cost-tracker`
hook enabled.

## Example — summary, by model, last 7 days

```bash
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("cost log not found: "+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("today: "+f4(sum(latest.filter(r=>day(r)===today)))+" | yesterday: "+f4(sum(latest.filter(r=>day(r)===yest)))+" | total: "+f4(sum(latest))+" ("+latest.length+" sessions)");
const m=new Map();for(const r of latest){const k=r.model||"(unknown)";m.set(k,(m.get(k)||0)+cost(r));}
console.log("by model:");[...m.entries()].sort((a,b)=>b[1]-a[1]).forEach(([k,v])=>console.log("  "+f4(v)+"  "+k));
'
```

For a session drilldown or CSV export, iterate the same `latest` set (or the raw
rows for CSV) and print the fields you need.

## Reporting Guidance

When presenting cost data, include today's spend vs yesterday, total across all
sessions, a by-model breakdown, and session count. Format sub-dollar amounts
with four decimals, larger amounts with two.

## Anti-Patterns

- Do not sum every row — they are cumulative per session; reduce to the latest
  row per `session_id` first.
- Do not estimate costs from raw token counts when `estimated_cost_usd` is present.
- Do not assume the log exists without checking.
- Do not hard-code current model pricing in user-facing answers.
- Do not recommend installing unreviewed hooks or plugins that execute arbitrary code.

## Related

- `/cost-report` - Command-form report over the same metrics log.
- `cost-aware-llm-pipeline` - Model-routing and budget-design patterns.
- `token-budget-advisor` - Context and token-budget planning.
- `strategic-compact` - Context compaction to reduce repeated token spend.