# tokengazer

> A GitHub-style contribution graph for the AI tokens a developer uses in Claude Code and OpenAI Codex. A CLI reads local session logs, uploads only daily token totals per tool and model, and the server renders an embeddable SVG card for each GitHub username.

Prompts, code, file paths and project names never leave the user's machine. GitHub sign-in uses device flow with no scopes; the server reads the username once and discards the token.

## Usage

- `npx tokengazer`: print local stats. Nothing is uploaded.
- `npx tokengazer login`: GitHub device login, installs an hourly upload job (launchd on macOS, crontab on Linux), first push.
- `npx tokengazer push`: upload now.
- `npx tokengazer logout [--delete]`: remove the hourly job and local key; `--delete` also erases the user's data from the server.

Embed snippet (Markdown):

```md
[![tokens](https://tokengazer.vercel.app/<github-username>.svg)](https://tokengazer.vercel.app/<github-username>)
```

## Public endpoints

- [https://tokengazer.vercel.app/<github-username>.svg](https://tokengazer.vercel.app/kunatastic.svg): embeddable card, cached 1h. Unknown users get a "not tracking yet" card.
- [https://tokengazer.vercel.app/<github-username>](https://tokengazer.vercel.app/kunatastic): HTML profile with per-model breakdown; `?year=YYYY` selects a year.
- [https://tokengazer.vercel.app/<github-username>.json](https://tokengazer.vercel.app/kunatastic.json): `{ login, rows: [{ day, tool, model, input, output, cache_read, cache_write, reasoning, estimated }] }`, CORS enabled.

## How tokens are counted

- Claude Code: `~/.claude/projects/**/*.jsonl`. Tokens = input + output + cache reads + cache writes.
- Codex: `~/.codex/sessions/**/*.jsonl` (and `.jsonl.zst` on Node >= 22.15). Tokens = input + output.
- Estimated history: Claude Code deletes session logs after 30 days. Older days are estimated as prompt count (from `~/.claude/history.jsonl`) times median tokens per prompt, split by model using `~/.claude/stats-cache.json`. Rows carry an `estimated` flag. Setting `"cleanupPeriodDays": 3650` in `~/.claude/settings.json` keeps exact history.
- Cost is the API list-price equivalent, not subscription spend.

## Links

- [Source code and README](https://github.com/kunatastic/tokengazer): MIT licensed.
- [npm package](https://www.npmjs.com/package/tokengazer)