Claude Usage Analytics
krishnesh7/claude-usage-analytics
Analytics local de tokens e custos para Claude Code com dashboard interativo
Ver no GitHubPlugin que analisa consumo de tokens e custos da API Claude de forma local, sem envio de dados. Integra parser incremental, banco SQLite, dashboard em tempo real e pontuação de eficiência por projeto e estágio de desenvolvimento.
Instalação
npx convez-ai krishnesh7/claude-usage-analytics1 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
- Monitorar consumo de tokens e custos por projeto
- Analisar eficiência de cache e custo por estágio SDLC
- Comparar pricing entre modelos e modos de pagamento
- Gerar relatórios de uso e recomendações de otimização
Veredito

Ferramenta robusta para quem precisa rastrear custos de Claude com rigor financeiro. Execução local garante privacidade; dashboard e slice por SDLC stage agregam valor real para planejamento de sprints.
README
A tradução para o português deste README ainda está na fila.
claude-usage-analytics
Local-first token usage & imputed-cost analytics for Claude Code. Parses your
~/.claude/projects session transcripts into SQLite and surfaces them through a
live dashboard, static HTML reports, slash commands, and an in-project
CLAUDE_USAGE.md. Everything runs offline on your machine — no data leaves it,
and there's near-zero LLM overhead (the parser is pure code).
What it tracks
- Token usage and imputed API-equivalent $ cost per project, SDLC stage, and model
- Cost modes — toggle between API (pay-per-token), Conservative (blended cache estimate), and Subscription (flat-plan imputed) pricing, with auto-detected default based on your plan
- Efficiency scoring — per-project efficiency across 4 axes (Cache Hygiene, Cache Payback, Model Fit, Cost Economy) with percentile ranks and actionable recommendations
- Session-kind split (user vs subagent vs tracker) so totals aren't double-counted
- Cache-hit rate per project / stage / model
- Per-day stacked trend chart (user vs subagent)
- Cleaned session labels, secret redaction on every display surface
Prerequisites
The plugin auto-creates its Python venv and installs its own dependencies on first run, but it assumes these are already on your machine:
| Tool | Required | Used for |
|---|---|---|
| Python ≥ 3.10 | yes | the cu CLI + dashboard |
| Node.js | yes | the transcript parser (parse.mjs) |
| Internet (first run only) | yes | one-time pip install of deps |
jq, sqlite3 | optional | hook conveniences; degrade gracefully if absent |
Without Node, the database never populates and reports show zeros.
cu parseprints a warning to stderr ifnodeis missing.
Install
/plugin marketplace add krishnesh7/claude-usage-analytics
/plugin install claude-usage-analytics
Then just start a Claude Code session. The SessionStart hook runs bin/cu,
which on first use:
- creates a private venv under the plugin and
pip installs the package, - creates the SQLite DB + seeds config defaults,
- migrates any existing
~/.claude/usagehistory, - begins parsing your sessions in the background.
No manual setup.
Slash commands
| Command | Does |
|---|---|
/usage | Token + cost summary for this project (last 7 days) |
/usage-report | Self-contained interactive HTML report |
/usage-doc | Write/refresh docs/usage/CLAUDE_USAGE.md |
/usage-parse | Force a re-parse |
/stage | Set this session's SDLC stage |
/project-init | Register the current directory as a project |
/project-list | List registered projects with totals |
/project-confirm | Verify/correct this session's project tag |
/usage-guide | Getting-started guide |
/usage-compare | Compare vs the official session-report plugin |
Live dashboard
cu serve # http://localhost:7777, auto-refreshes every 30s
While serving, a background loop re-parses every 60s so in-flight sessions appear without a manual refresh. The dashboard has time + kind filters, sortable tables, an efficiency panel with per-project scores and recommendations, project → stage → session drill-down navigation with breadcrumbs, hover tooltips on key metrics, and session search.
Configuration
| Env var | Default | Purpose |
|---|---|---|
CU_DATA_DIR | ${CLAUDE_PLUGIN_ROOT}/data (else ~/.claude/usage) | Where the DB + config live |
CU_REDACT_PROMPTS | mask | Secret redaction mode: mask / hash / off |
CU_SERVE_AUTO_PARSE_SEC | 60 | Dashboard background re-parse interval (0 disables) |
Pricing lives in <data dir>/prices.json (USD per 1M tokens). The DB stores raw
token counts, so editing prices reprices all history retroactively.
Privacy
- All data stays in your local SQLite DB; nothing is transmitted.
- Prompt content is redacted (9 secret patterns) before it reaches the
dashboard, static report, or
CLAUDE_USAGE.md. - The data dir (DB, history) is git-ignored and never committed.
Development
git clone https://github.com/krishnesh7/claude-usage-analytics
cd claude-usage-analytics
python3 -m venv .venv && .venv/bin/pip install -e .
.venv/bin/cu --help
Run from a checkout and cu resolves the parser at ./parser/parse.mjs and the
data dir at ~/.claude/usage (no CLAUDE_PLUGIN_ROOT).
License
MIT