SpendWatch
edihasaj/spendwatch
Leaderboards de gasto em tokens/$ entre agentes de código para otimizar custos
Ver no GitHubAgent que analisa transcripts locais de ferramentas de codificação (Claude Code, Codex, Copilot, Gemini) e gera leaderboards de custo em tokens e dólares. Identifica quais tool calls, comandos shell e prompts consomem mais recursos, facilitando otimização de automação e detecção de gargalos.
Instalação
npx convez-ai edihasaj/spendwatch1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Auditar consumo de tokens entre diferentes agentes de IA
- Identificar tool calls e comandos que mais custam para automatizar
- Detectar ferramentas ou prompts que despejam resultados enormes no contexto
- Monitorar histórico de gastos com múltiplas contas de agentes
Veredito

Ferramenta focada e sem dependências para auditoria de custos em agentes de código. Essencial para quem trabalha com múltiplos agentes e precisa otimizar gastos com API; reportes HTML interativos e exportação SQLite agregam valor real.
README
A tradução para o português deste README ainda está na fila.
spendwatch
Token/$ leaderboards across coding agents (Claude Code, Codex, …): which tool calls, shell commands, and prompts spend the most — so you know what to automate (build a CLI for ssh/git diff/docker compose…) or fix (a tool dumping huge results into context).
Parses each agent's local transcripts. Zero runtime deps, Bun. Agents are split out, with a cross-agent overview on top.
Privacy: spendwatch reads your local transcript files and writes local reports only. It makes no network calls and sends nothing anywhere.
Install
Requires Bun. Run from source, or compile a standalone binary:
git clone https://github.com/edihasaj/spendwatch && cd spendwatch
bun run report # run directly
bun run build # → bin/spendwatch (self-contained, embeds Bun + SQLite)
install -m 0755 bin/spendwatch /opt/homebrew/bin/ # optional: put on PATH
Usage
bun src/cli.ts report # all agents, past 30 days
bun src/cli.ts report --agent codex # one agent (claude,codex,copilot,gemini)
bun src/cli.ts report --project chat-sql # filter by project substring
bun src/cli.ts report --days 7 --json
bun src/cli.ts report --html # also write a standalone HTML report
bun src/cli.ts report --open # write HTML + open it in the browser
bun src/cli.ts report --brief # TL;DR: total, biggest hog, top automate targets
bun src/cli.ts report --sqlite # append a snapshot to spendwatch.db
bun src/cli.ts report --account work # filter by account (email/label)
bun src/cli.ts watch # live leaderboard, refreshes as sessions write
bin/spendwatch report # compiled binary (bun run build)
--html [path] writes a self-contained, shareable index.html (default spendwatch-report.html): cross-agent overview, per-agent tabs, every table with heat bars, and click any tool/command row to drill into the actual invocations (which files, which commands, with counts + token cost) — the "what to automate" view. --open writes it and opens it.
--sqlite [path] appends a normalized snapshot (one run per call) so you can build spend history and query with SQL — tables: runs, agent_account, tools, commands, prompts, models, projects, samples.
Multi-account
Accounts are auto-detected per agent (Claude ~/.claude.json email, Codex auth JWT email). Reports tag by account but sum per agent. For multiple accounts in different config dirs, create ~/.config/spendwatch/config.json (or $SPENDWATCH_CONFIG):
{ "roots": [
{ "agent": "claude", "account": "work", "path": "~/.claude/projects" },
{ "agent": "claude", "account": "personal", "path": "~/personal/.claude/projects" },
{ "agent": "codex", "account": "work", "path": "~/.codex/sessions" }
] }
Each account shows under BY ACCOUNT; the agent total (and overview) sum across them. Filter with --account <substr>.
Sources
| agent | logs | token usage |
|---|---|---|
| Claude Code | ~/.claude/projects/**/*.jsonl | ✓ |
| Codex CLI | ~/.codex/sessions/**/rollout-*.jsonl | ✓ |
| Copilot CLI | ~/.config/github-copilot | ✗ (binary Xodus store, no usage) |
| Gemini CLI | ~/.gemini | ✓ when present |
Copilot/Gemini are detected and reported as footnotes until parseable logs exist. Adding a new agent = one parser emitting the shared Event model + a sources.ts entry.
What to automate
The AUTOMATE — top targets list (top of the report, and --brief) ranks shell commands by cost × frequency × friction — the build-a-CLI/MCP shortlist. Friction is measured, not guessed: Claude tool_result.is_error and Codex exit codes. A why column tells you the driver:
frequent + costly— high spend, lots of calls → wrap it in one toolfails N% · flaky— the command errors often (the agent retries, burning tokens)exit-127 · agent guessing— command-not-found: the agent doesn't know this tool → give it a CLI/MCP
Honesty note: spendwatch does not invent a "you saved $X" number — that's an unmeasurable counterfactual. It shows observed cost and measured friction (error/retry rate). After you automate something, its cost and error rate drop and you see it in the data.
What the numbers mean
- $ — from real per-request
usagefields (Claude:cache_creation/cache_read; Codex:last_token_usage, summed — verified equal to cumulative). Prices/MTok: Fable $10/$50, Opus $5/$25, Sonnet $3/$15, Haiku $1/$5, gpt-5 tier $1.25/$10 (Codex $ is an estimate — it's largely subscription-billed). Cache: write 1.25× (5m)/2× (1h), read 0.1×. - ctx $ (per tool/command) — est. cost a call's results impose on the session: result tokens (chars/4) × one cache write + a 0.1× reread on every later request in that session. Big outputs early in long sessions cost the most.
- BY COMMAND — shell calls split by executable (
echo,docker,grep,ssh…), skippingcd X &&/env/wrappers. - BY COMMAND — DEEP — executable + subcommand (
git diff,docker compose,pnpm lint) and, forssh, the remote command head. This is the "what to build a CLI for" list. - BY PROMPT — spend attributed to the active prompt (
⑂= subagent / Codex task).
Layout
src/pricing.ts— price table + cost functions (incl. cache multipliers)src/parse.ts— Claude JSONL → events;commandPath()deep shell breakdownsrc/codex.ts— Codex rollout JSONL → same eventssrc/sources.ts— agent registry: log locations, discovery, account detection, config rootssrc/aggregate.ts— per-session fold → leaderboards + per-account + drill-down samplessrc/db.ts— SQLite snapshot writer (bun:sqlite)src/html.ts— standalone HTML report with tabs + drill-downsrc/scan.ts— file walk + incremental offsets (watch mode)src/render.ts/src/cli.ts— tables, cross-agent overview, report/watch
Test
bun test # claude + codex fixtures with hand-computed costs, deep-command,
# incremental append, multi-account sum/breakout, sqlite round-trip
Contributing
Adding another agent is one parser emitting the shared Event model plus a sources.ts entry. PRs welcome.
License
MIT © Edi Hasaj