Claude Stats

Your Claude Code usage, as a live stats card for your GitHub profile.

Sessions, prompts, tokens, models, top tools and an activity heatmap — computed locally from your Claude Code history, rendered as a self-contained SVG and refreshed automatically.

• Features
• Requirements
• Quick start
• Commands
• Customization
• Several computers
• How it works
• Privacy
• How the numbers are computed
• Troubleshooting
• Upgrading from claude-usage-chart
• Uninstall
• Contributing
• Disclaimer · License

• Complete overview — sessions, prompts, active days, longest streak, generated tokens, tool calls, peak hour and favorite model.
• Activity heatmap — prompts per day, from 8 to 52 weeks.
• Token and model breakdown — what Claude wrote, what was added to context, what was re-read from cache, and the share of each model.
• Same numbers as the Claude app — sessions, messages, tokens and peak hour are counted like the app's own stats card (see below).
• Fully customizable — dark, light or auto theme, 6 heatmap palettes, accent color, title, tiles and sections.
• Automatic refresh — from every hour to once a week, only committing when something changed.
• Private by design — only aggregated numbers leave your machine.
• Zero dependencies — a single Node.js CLI, works on Windows, macOS and Linux.

• Node.js 18 or later
• Claude Code with some local history in ~/.claude/projects
• A GitHub token, from either:
  • the GitHub CLI (gh auth login) — recommended, or
  • a GITHUB_TOKEN environment variable with write access to the target repository (contents: write)

Install the latest release, then run the guided setup:

npm i -g https://github.com/Clovis500c/claude-stats/releases/latest/download/claude-stats.tgz
claude-stats setup

Or run it without installing anything:

npx -y --package=https://github.com/Clovis500c/claude-stats/releases/latest/download/claude-stats.tgz claude-stats setup

The setup will:

1. read your local Claude Code history (~/.claude/projects);
2. render the card (dark theme by default);
3. upload it to your profile repository (<you>/<you> by default);
4. ask how often it should refresh (every hour to once a week, or never);
5. print the snippet to paste into your README.md:

<img alt="Claude Code usage" src="https://raw.githubusercontent.com/<you>/<you>/HEAD/claude-stats/claude-stats.svg" />

setup asks for the main options; every option can also be passed on the command line. Options are remembered by the automatic refresh.

Available tiles: sessions, messages, prompts, activeDays, streak, generated, toolCalls, peakHour, favorite, responses, processed.

--palette green --accent "#39d353" --weeks 52	--palette purple --accent "#8c70e6" --title "My AI pair-programming" --hide tokens,models,tools
--theme light --palette pink --accent "#cc4589" --hide tools	--tiles prompts,generated,streak,favorite --hide heatmap,tools --palette orange
--hide header,tiles,book,tokens,models,tools --palette gray --transparent	--cost --hide tiles,heatmap,book,tokens,models,tools

With --theme auto, two files are published (claude-stats.svg and claude-stats-light.svg) and setup prints a <picture> snippet so GitHub shows the one matching each visitor's theme.

Your history only exists on the computer it was written on, so with two PCs each one would draw a card from its own half and the last one to upload would win. To add them up, give every computer the same folder, one you already sync between them (OneDrive, Dropbox, Syncthing, a NAS, even a USB key):

claude-stats setup --sync-dir "C:UsersyouOneDriveclaude-stats"   # on each computer

setup also asks for it, and offers to install the hooks below. Each computer writes a small snapshot of itself (<hostname>.claude-stats.json.gz, a couple of MB) into the folder, reads the snapshots of the others, and renders the card from the sum.

claude-stats hook install --sync-dir <path> adds a Stop and a SessionEnd hook to Claude Code's settings.json (backed up once as settings.json.bak-claude-stats; your other hooks are left alone; claude-stats hook uninstall removes only these). After every Claude Code response, the hook starts a detached claude-stats sync --background and returns at once, so it never slows Claude down. Only the transcripts that changed are read again (the rest comes from a local cache), so a save takes about a second once the cache is warm (about 15 s the very first time). The hook runs the installed claude-stats: install it globally first, and update it when a new version comes out.

• The other PC can be off. Its last snapshot stays in the folder, so this computer still counts it; and the other PC saved right after its last response, so it can't be more than a few seconds behind.
• Fully offline: nothing goes through a server; the folder is the only link.
• No conflicts: a computer only ever writes its own file.
• Same card everywhere: once the snapshots have synced, every computer computes the same totals, so it doesn't matter which one uploads.
• If the folder is unreachable (offline OneDrive placeholder, unplugged drive, file still downloading), the last good copy of each other computer, kept in ~/.claude-stats-peers, is used instead of dropping it from the card. With OneDrive, mark the folder "Always keep on this device". A computer you delete from the folder is forgotten.
• Check it: claude-stats sync --sync-dir <path> lists the sessions, messages and prompts of each computer. If a background save fails, the reason is in ~/.claude-stats-sync.log (the file only exists while the last one failed).
• Manual runs: pass --sync-dir again, or set CLAUDE_STATS_SYNC_DIR once, otherwise a manual push would upload a single-computer card.
• Two computers with the same hostname would overwrite each other: give one a different --machine <name>.
• Sessions, prompts and tool calls are de-duplicated across computers by their ids; the app-style messages and tokens are simply added up, which is right as long as the computers don't hold copies of the same transcripts.

~/.claude/projects/**/*.jsonl ──► aggregate (local) ──► SVG card ──► GitHub contents API ──► your README

Tools like the contribution snake read data that already lives on GitHub. Your Claude Code usage only lives on your computer — there is no public API for personal (Pro/Max) usage. The refresh therefore runs locally and pushes the SVG; the card updates whenever your machine is on.

A job (Task Scheduler on Windows, cron on macOS and Linux) wakes up every hour and only uploads once the chosen interval has elapsed since the last successful upload. If your computer was off when a refresh was due, it happens within an hour of being back on. Nothing is committed when the numbers haven't changed.

Only aggregated numbers end up in the SVG: counts, token totals, per-day prompt counts, model names and the names of your most-used tools. No prompts, code, file names or project names ever leave your machine. Use --hide tools to leave tool names off the card. The spend banner is off by default, since it shows an amount of money on your public profile.

With --sync-dir, the snapshot written to that folder holds the same kind of data plus timestamps, session ids and per-response token counts, never any prompt, code or file name. It stays in your folder and is only as private as the sync tool you chose.

The GitHub token is read from gh or GITHUB_TOKEN at run time and is never stored by this tool. The only file it writes outside the output folder is ~/.claude-usage-chart.json, which records the time of the last upload per repository.

Messages, tokens (tiles, Tokens and Models bars, book line) and peak hour are counted like the Claude app's stats card, so both show the same numbers: every user/assistant line of a transcript is a message, and the token usage of every line is summed, subagents included. Since one response is written as several lines repeating the same usage, this counts a response several times (about 3.5× on a typical history).

Everything else is de-duplicated, because Claude Code transcripts (~/.claude/projects/**/*.jsonl) contain a lot of repetition:

• one API response is written as several lines (one per content block), each repeating the same token usage → each response is counted once;
• resumed sessions copy earlier messages into a new file → each message is counted once;
• most "user" lines are tool results or system notices → only messages you actually typed count as prompts;
• subagent prompts and tool calls are excluded (the spend banner includes subagents: they are billed too).

The spend banner is always de-duplicated: it estimates what was actually billed.

--cost adds a banner with the cost of your Claude Code usage over the last 30 days, 5 months or 12 months (--cost-period 30d|5m|1y; months are calendar months), estimated at Anthropic API list prices, like Claude Code's own cost display. Each response is priced by model: input, cache writes (1.25× input for the 5-minute cache, 2× for the 1-hour cache), cache reads, output, fast mode (2×) and web searches ($10 per 1,000). Subagents are included.

The banner's look climbs with the average per 30 days, so a longer window doesn't inflate it: Bronze (under $100), Silver ($100+), Gold ($500+, sparkles), Diamond ($1,500+) and Legendary ($5,000+, flowing rainbow). The glint and sparkles are animated, and stay still for visitors who prefer reduced motion.

This is not what you paid. The banner itself says so ("at API prices, not the amount paid"): on a Pro or Max plan it is the API value of what you used, while the subscription price stays the same. It only covers the history still on your machine: Claude Code deletes transcripts older than 30 days unless you raise cleanupPeriodDays in its settings, so a 5- or 12-month window can show less than you really used. Responses from models without a known price are left out; claude-stats (without push) prints how many.

claude-stats unschedule
npm rm -g claude-stats
rm ~/.claude-usage-chart.json   # optional: last-upload bookkeeping

Then remove the claude-stats/ folder and the snippet from your profile repository.

Issues and pull requests are welcome.

git clone https://github.com/Clovis500c/claude-stats.git
cd claude-stats
npm test                 # unit tests (node:test, no dependencies)
npm run preview          # render your own card to preview/claude-stats.svg

1. Bump version in package.json and move the Unreleased notes in CHANGELOG.md under the new version.
2. Tag and push (git tag v0.6.0 && git push origin v0.6.0), or run the Release workflow from the Actions tab, which tags the current commit for you.
3. The release workflow runs the tests, packs claude-stats.tgz and publishes the GitHub release.

Created and maintained by Clovis500c. If you find it useful, a ⭐ on the repository is appreciated.

This is a community project, not affiliated with or endorsed by Anthropic. Claude and the Claude logo are trademarks of Anthropic, used here only to identify the product the stats are about. The logo path comes from Simple Icons (CC0).