claude-usage-graph
convenientlymike/claude-usage-graph
Turn your Claude Code token usage into a beautiful 3D isometric calendar — a contribution-graph-style card from your local session transcripts. Aggregate counts only; zero required deps.
Instalação
npx convez-ai convenientlymike/claude-usage-graph1 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
README
A tradução para o português deste README ainda está na fila.
🧊 claude-usage-graph
Turn your Claude Code token usage into a beautiful 3D isometric calendar.
A GitHub-contribution-style card — built from your local Claude Code session transcripts, rendered as a self-contained SVG (and optional PNG). Aggregate counts only, so it's safe to put on your profile.
▶️ Try it
- Live playground → — paste your usage JSON (or use the built-in sample), switch themes, download the card. Runs entirely in your browser.
- One-liner (no install — runs from GitHub via
npx):npx github:convenientlymike/claude-usage-graph --png # → claude-usage.svg + claude-usage.png, built from ~/.claude/projects
Why
ccusage and /usage tell you the numbers.
This turns those numbers into something you'd actually show — a calendar where each
day is a little cube whose height and color scale with how hard you ran Claude Code that
day. Drop it on your GitHub profile next to your contribution graph, in a README, or a
dashboard. It reads the same local transcripts, emits only aggregate daily counts
(never project names, paths, or message content), and produces a self-contained SVG that
renders identically everywhere.
✨ Features
- 🧊 3D isometric calendar — one cube per day; height + color scale with that day's token volume (√-scaled so a 50× peak doesn't flatten the quiet days). Plus a hero stat — total · active days · daily average · peak day — and a per-model split bar.
- 💵 Dollar value — converts your tokens to USD at Anthropic's list API prices (per
model: Opus / Sonnet / Haiku, verified 2026-06). Cache tokens are priced as output
tokens — input at the input rate, everything else (output + cache) at the output rate.
The card shows a clean figure;
--cost offhides it. (List price for scale, not a subscription bill — that caveat lives in the docs, not on the image.) - 🔒 Aggregate counts only — reads token counts, timestamps, and the model id; never
project names, file paths, prompts, or content.
--emit-jsonwrites exactly what gets rendered so you can audit what you share. Safe for a public profile by construction. - 🪶 Zero required runtime dependencies — the aggregate + SVG core is pure
TypeScript. PNG is an optional extra (
@resvg/resvg-js), loaded only for--png. - 🖼 Native SVG, renders everywhere — plain SVG primitives (no
<foreignObject>), so it looks identical on GitHub, iOS Safari, and any rasterizer.--pngfor a crisp, transparent, Retina-scaled raster. - 🎨 Four themes —
brand(violet→cyan),github(greens),amber,mono. - 🧰 CLI + library — script it (
renderSVG(aggregateDir())) or run it; cross-platform (macOS · Linux · Windows), Node ≥ 22.
📸 Themes
🚀 Quickstart
# Run it without installing (from GitHub):
npx github:convenientlymike/claude-usage-graph --png --stats
# Or install globally:
npm i -g claude-usage-graph # then: claude-usage-graph --png
claude-usage-graph --theme github -o card.svg --png
By default it reads ~/.claude/projects (where Claude Code stores session transcripts)
and writes claude-usage.svg to the current directory.
| Need | Command |
|---|---|
| SVG card (default) | claude-usage-graph |
| SVG + PNG, github theme | claude-usage-graph --theme github -o card.svg --png |
| Print a usage summary | claude-usage-graph --stats |
| Just the data (counts only) | claude-usage-graph --emit-json usage.json |
| Render from a saved JSON | claude-usage-graph --json usage.json -o card.svg |
| A different transcripts dir | claude-usage-graph --dir /path/to/projects |
CLI options
-o, --out <file> output path (default: claude-usage.svg; .png implies --png)
--png also write a PNG (needs the optional @resvg/resvg-js)
-s, --scale <n> PNG device scale (default 3 — crisp on Retina)
--theme <name> brand (default) · github · amber · mono
--cost <mode> USD figure (list price): io (input+output, default) · all-in · off
--title <text> header title
--dir <path> transcripts dir (default ~/.claude/projects)
--json <file> render from an emitted/compatible JSON instead of transcripts
--emit-json <f> write the aggregate JSON (counts only)
--stats print a usage summary
-h, --help · -v, --version
🔒 Privacy
The whole point is that this is safe to publish. The parser reads only:
- token counts (
input/output/cache_creation/cache_read), - the message timestamp, and
- the model id.
It never reads — and the output never contains — project names, file paths, prompts, or
any message content. Want to be sure? --emit-json usage.json writes the exact
{ byDay, byModel } count map that gets rendered; inspect it, then --json usage.json to
render from it on any machine. No network calls, no telemetry.
Heads up: like
ccusage, the total is dominated by cache-read tokens — that's normal for Claude Code (every turn re-reads cached context). The--statsview breaks it down.
💵 What the dollar figure means
The USD is computed at Anthropic's list API prices, per model (e.g. Opus 4.5+ at
$5 / $25 per Mtok input/output, Sonnet at $3 / $15, Haiku 4.5 at $1 / $5; verified
2026-06 from the pricing page).
- Cache is priced as output.
cost = input × inputRate + (output + cacheCreate + cacheRead) × outputRate. Anthropic's cheaper cache rates are deliberately not applied, so it's a simple, on-the-high-side figure rather than a precise metered cost. - It is not your bill. If you're on a Claude Pro/Max subscription, you pay a flat
fee — this is the equivalent list-price value, shown for scale.
--cost offhides it. - The card shows only the dollar number — this basis note is kept here in the docs, off the image, on purpose.
--stats prints it. Rates live in src/pricing.ts.
🏗 How it works
~/.claude/projects/**/*.jsonl aggregate (counts only) render
┌─────────────────────────┐ ┌───────────────────────────┐ ┌──────────────┐
│ assistant turns carry │ │ byDay: {date -> quad} │ │ isometric │
│ message.usage + timestamp│ ───▶ │ byModel:{model -> quad} │──▶│ SVG card │──▶ .svg
│ + model │ │ totals, range, peak │ │ (+ optional │──▶ .png
└─────────────────────────┘ └───────────────────────────┘ │ resvg PNG) │
parse, sum — no content └──────────────┘
src/aggregate.ts— walk transcripts → per-day / per-model token quads (or load a JSON).src/render.ts— isometric geometry + theming → a self-contained SVG string.src/png.ts— lazy@resvg/resvg-jsrasterization (optional).src/cli.ts— the command-line surface.
Library
import { aggregateDir, renderSVG, renderPNG } from "claude-usage-graph";
const agg = aggregateDir(); // parse ~/.claude/projects
const svg = renderSVG(agg, { theme: "brand", title: "MY CLAUDE YEAR" });
const png = await renderPNG(svg, 3); // Uint8Array (optional dep)
📌 Put it on your GitHub profile
- Generate the PNG:
claude-usage-graph --png -o assets/claude-usage.png - Commit it and embed it in your profile
README.md:<img src="assets/claude-usage.png" width="100%" alt="My Claude Code token usage" /> - To keep it fresh, regenerate on a schedule (cron / launchd / a Git hook) and commit.
(macOS tip: scheduled jobs can't read
~/Desktop/~/Documentsdue to privacy — keep the repo clone somewhere like~/.cachefor the automation.)
Project layout
src/
aggregate.ts parse transcripts / JSON → token quads
render.ts 3D isometric SVG + themes
png.ts optional resvg-js rasterization
cli.ts command-line interface
index.ts library exports
test/ node --test (+ a JSONL fixture)
docs/ GitHub Pages playground + screenshots
examples/ a sample aggregate (used by the README + playground)
Supported OS
macOS · Linux · Windows (CI runs the full matrix). Node ≥ 22.
Security
See SECURITY.md. TL;DR: local-only, no network, aggregate counts only.
License
MIT © convenientlymike