$ show phuryn/claude-usage
A well-crafted, self-contained application for analyzing and visualizing Claude Code usage logs. The system reads local JSONL transcript files (written by Claude Code regardless of subscription plan), parses them into a local SQLite database, and surfaces token counts, cost estimates, session histories, and subagent attribution through both a terminal CLI (`python cli.py today` / `stats` / `week`) and a rich single-page web dashboard (`python cli.py dashboard`). The dashboard is served by a stdlib-only Python HTTP server and bundles all HTML/JS/CSS inline, using Chart.js from CDN for visualizations. A companion VS Code extension embeds the same dashboard as a sidebar webview, auto-discovering the Python runtime via a flexible install-mode resolution chain (bundled `.py` sources, Homebrew shim, workspace clone, or explicit path). Architecturally, the code is split into three top-level Python modules—`scanner.py` (JSONL parsing, SQLite schema management, incremental scanning with deduplication by message ID), `cli.py` (CLI dispatch with per-turn cost calculation using a tiered pricing lookup), and `dashboard.py` (HTTP server with an embedded SPA). There are no third-party Python runtime dependencies; the VS Code extension uses TypeScript with minimal Node.js dependencies (only `@vscode/vsce` for packaging). The test suite is comprehensive, covering unit, integration, and HTTP-level scenarios across all three Python modules plus the entire TypeScript extension. A strict version parity test (`test_version.py`) enforces lockstep between the Python constant, the CHANGELOG heading, and the extension's `package.json`. Notable craftsmanship includes: the incremental scan engine that tracks file mtimes and line counts, processes only new/changed lines, and deduplicates streaming events via a conditional unique index on `message_id`; the one-time topic backfill mechanism for schema upgrades that re-reads only title records without touching token totals; and the VS Code extension's server-manager with configurable readiness probes that distinguishes the dashboard's JSON response shape from arbitrary HTTP 200s. The project is actively maintained with frequent releases, a weekly triage automation, and a detailed AGENTS.md that documents non-obvious invariants (streaming dedup, session model priority, cost calculation per-turn).
The LLM identified 4 files worth highlighting for reuse:
The core scanning module that parses Claude Code JSONL transcripts into a SQLite database. Implements incremental scanning by tracking file mtimes and line counts; deduplicates streaming events by keeping only the last record per message ID; handles additive schema migrations (new columns, tables) via `init_db` with `_ensure_column` helpers. The one-time topic backfill pattern for pre-existing databases is a well-isolated, testable pattern. This module could be extracted as a standalone library for any tool that needs to consume Claude Code's local logs.
A pragmatic tiered pricing resolver that tries exact model name match, then prefix match (handles date-suffixed model IDs like `claude-opus-4-7-20260215`), then substring fallback on family keywords (fable, mythos, opus, sonnet, haiku). The per-turn cost calculation sums input, output, cache_read, and cache_creation tokens at their respective rates. The same logic is duplicated in the dashboard's JavaScript (with a parity test enforcing sync), but the Python version is cleanly separated and could be reused in any cost-aware tooling. The fallback strategy avoids silently mispricing unknown local models (returns `None`, billed as $0).
A clean abstraction for spawning a local Python HTTP server, probing it until healthy, and cleaning up on disposal. Supports configurable probes (default uses a strict JSON-shape check on `/api/data` to avoid confusing the dashboard with any random localhost service), timeouts, and stdout/stderr forwarding. The `SpawnedLike` interface makes it trivially testable with fake processes (as done in the test suite). This pattern is directly reusable for any VS Code extension that needs to run a local backend process.
Resolves how to invoke the dashboard CLI: via Homebrew shim, bundled Python sources, workspace folder clone, or explicit user setting. The resolution chain is prioritized and well-documented (explicit setting → bundled → PATH → workspace → monorepo sibling → none). The `dashboardSpawnArgs` function cleanly decouples install mode from spawn arguments, making the resolver testable in isolation. This pattern is applicable to any multi-path executable discovery in developer tools.