English · 한국어
A terminal dashboard for the token usage Claude Code already writes to disk.
It reports on the directory you are standing in — what Claude did here —
rather than dumping every project you have ever opened. No dependencies, no
API calls, no account of its own: it reads the transcripts Claude Code leaves
in ~/.claude.
TokenMeter overview all projects updated 07:40:16
all projects 81 req / 1 proj / 1 sess
┌─ USAGE ──────────────────────────────────────────────── quota read 2m ago ─┐
│ 5h limit ████████████░░░░░░░░░░░░░░░░░░░░░░░░ 34% resets in 3h 11m │
│ 09-22 07:00 - 12:00 out 840 cache r 114.0k hit 98.8%│
│ weekly limit ██████████████████████░░░░░░░░░░░░░░ 61% resets in 3d 9h │
│ 09-15 - 09-22 out 89.0k cache r 13.3M hit 98.9%│
└────────────────────────────────────────────────────────────────────────────┘
┌─ DAILY ──────────────────────────────────────────────────── 09-16 - 09-22 ─┐
│ DATE in + cache + out TOTAL│
│ 09-16 █████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 811.7k│
│ 09-17 ···························································· -│
│ 09-18 █████████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 2.3M│
│ 09-19 ████████████████████████████████████████████████████████████ 5.6M│
│ 09-20 ███████████████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 2.9M│
│ 09-21 ██████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 1.7M│
│ 09-22 █░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 116.2k│
└────────────────────────────────────────────────────────────────────────────┘
┌─ BY MODEL ───────────────────────────────────────┐┌─ CACHE ────────────────┐
│ opus-5 ██████████████████ 81 req 98.9%││ hit 98.9%│
└──────────────────────────────────────────────────┘│ saved 13.3M│
│ cache wr 142.1k│
└────────────────────────┘
[1]overview [2]sessions [3]daily [r]eload [l]ang [q]uit
pip install git+https://github.com/aidevksh/tokenmeter
Then, in any project directory:
tokenmeter
That is the whole setup. pip puts a tokenmeter command on your PATH —
tokenmeter.exe on Windows, which works in both PowerShell and cmd, and a
launcher script on macOS and Linux.
Other ways to install
From a clone, so you can edit it:
git clone https://github.com/aidevksh/tokenmeter
cd tokenmeter
pip install -e .
Isolated, if you prefer pipx:
pipx install git+https://github.com/aidevksh/tokenmeter
Or skip installing altogether — from a clone, this always works:
python -m tokenmeter
If the shell cannot find the command afterwards, pip's script directory is not on your PATH. This prints it:
python -c "import sysconfig; print(sysconfig.get_path('scripts'))"
Requires Python 3.8 or newer, and Claude Code having run at least once. Nothing else — the whole tool is the standard library.
tokenmeter # this directory
tokenmeter ~/src/thing # another directory
tokenmeter --all # every project at once
tokenmeter --once # print one frame and exit
| overview | account limits with your matching token totals, daily bars, model split, cache |
| projects | one row per project (appears only when the scope holds more than one) |
| sessions | sessions by title, detail for the selected one, throughput chart |
| daily | per-day table: requests, output, cache read/write, total |
Sessions are listed by the title Claude gave them, not by their id. Move through the list with the arrow keys and the detail panel follows.
1..4 switch screen s cycle sort (projects, sessions)
up/down select (also j/k) r re-read the logs now
enter drill into a project l toggle English/Korean
esc back q quit
Letter shortcuts also answer to the Korean 2-set layout, so r, q and l
still work with the IME in Hangul mode — ㄱ, ㅂ and ㅣ reach the same
commands, and you do not have to switch back to English first.
--all every project instead of one directory
--root PATH transcript root (default: ~/.claude/projects)
--lang en|ko override the detected language
--screen NAME start on overview | projects | sessions | daily
--days N days of history to chart (default 14)
--interval SEC seconds between live refreshes (default 1)
--once print one frame and exit; also automatic when piped
--no-color also honours NO_COLOR
--ascii +-| borders instead of box drawing
The display refreshes on its own, once a second by default. It re-reads the
transcripts only when one actually changes, so an idle dashboard costs a
stat per file per tick. The header carries the time of the last read.
The percentages in the overview are the real account limits — the same
numbers the Claude Code sidebar shows for Session (5hr), Weekly (7 day)
and any model-scoped limit. They are not derived from the transcripts, which
say nothing about your quota; they are read from cachedUsageUtilization in
Claude Code's own ~/.claude.json.
Two things follow from that:
- The gauges are account-wide, the token counts under them are not. The
numbers on the indented line are whatever this directory (or
--all) adds up to. The header says which directory that is. - The figure is as fresh as Claude Code left it. It refreshes that cache when it talks to the API, so the panel tag says how old the reading is. If the cache is missing entirely, the gauges are dropped rather than replaced with a guess.
Each gauge warms from green through yellow to red as it fills, so how close you are to a limit reads at a glance.
Two groups that never collide inside a row:
| judgement | green → amber → red: cache health, and the quota ramp |
| token kind | cyan output · blue cache read · orange cache write |
Everything structural stays grey. --no-color and NO_COLOR turn it all off.
Resolved in this order, first hit wins:
--lang~/.tokenmeter.json(written when you pressl)$TOKENMETER_LANG$LC_ALL,$LC_MESSAGES,$LANG- the OS setting — on Windows those variables are usually unset, so
GetUserDefaultUILanguage()is read instead - English
Token counts are read from ~/.claude/projects/<cwd-slug>/<sessionId>.jsonl,
the type: "assistant" lines, field message.usage. The quota percentages
come from ~/.claude.json (or $CLAUDE_CONFIG_DIR/.claude.json), key
cachedUsageUtilization.utilization.limits. Both are read-only.
- Requests are de-duplicated by
requestId. One request can appear on several lines; counting lines roughly doubles every total. cwdis not the project. It moves as youcdduring a session, so the transcript directory is the key and the shortestcwdunder it supplies the display name. That also recovers names the directory slug mangles, such as Korean ones.- 5-hour blocks are anchored to their first request, floored to the hour — the same shape as the rate-limit window.
<synthetic>messages are skipped; they are error placeholders with no usage.- Session titles come from the
ai-titlerecords Claude writes as the conversation goes on; the last one wins, and the first user prompt is the fallback. - Cost is not shown. The logs do carry what you would need for it, including
the 5-minute/1-hour cache-write split under
usage.cache_creation.
Text is measured in terminal cells, never characters — Hangul and CJK take two. Every column position derives from the panel width, so the same box holds in both languages and at any terminal size from 60 columns up.
Box-drawing and block characters are East Asian ambiguous width. Modern
terminals render them as one cell; if yours is configured otherwise, use
--ascii.
- Codex support. Read OpenAI Codex session logs alongside Claude Code's, so one dashboard covers both tools.
- Cost, once there is a price table worth trusting.
Apache 2.0. Copyright 2026 aidevksh.