Claude Code usage dashboard
A single self-contained HTML page that answers the questions /usage does not: where your Claude
Code hours actually went, which projects ate them, and whether this week's pace lands you on the
weekly limit or wastes half of it.
It reads the session logs Claude Code already writes to ~/.claude/projects/**/*.jsonl. No account,
no API key, no network. Pure Python, no dependencies.
→ Open the live demo (invented data, the real page) ·
the whole page in one image
Русская версия README
What it tells you
- What does an effort level really cost? Anthropic does not publish it. The dashboard prices it
from your own logs,
low → max: one call at each level against a call at high on the same model
version and at a similar context size, so neither a pricier model nor a longer context passes for
effort. Both the price against your limit and the output it writes, thinking included, for all
models or one at a time. On one real month: max = ×1.59 the price and ×1.91 the output of high,
medium = ×0.86; on Fable 5.1 alone xhigh costs ×1.56 of high, against ×1.14 across models.
- Am I going to hit the weekly limit? A calibrated gauge, not a guess:
k = actual ÷ plan, where
the plan follows when you actually work rather than the calendar. It says things like "you will
hit the limit on Wednesday around 11:00 and be without it for 1 d 8 h." Ticks on the week's bar
count the 5-hour windows that still fit before the reset; a cloud-session credit gets a bar of its own.
- Is my plan the right size? The paid month laid out week by week: each limit week against its
own limit, how it climbed hour by hour, what burned out unused, and a verdict — the plan fits, is
roomy, or sits at its ceiling and a bigger one pays off.
- Where did the time go? Active hours per project, grouped three ways (main work / work misc /
personal), by day, by month, and as a weekday × hour heatmap.
- What is the spend made of? Tokens by model, by context size, by effort level, by skill text
sitting in context, by subagent, by cold session start — each with a concrete suggestion.
- Did any of it ship? Commits from your local repos overlaid on the same timeline.
- How much of me is going into this, and when do I rest? A "Your time and rest" card first on the
board: your own time at Claude with parallel sessions merged, how long Claude was busy, your
longest stretch without a break and the night hours. The day's norm is 8 h on weekdays and 3 h at
the weekend and on the
holidays you list in the config; the week chart pages back through history; a line under today reads how many hours
Claude worked per hour of you and what to hand over so it works more and you less. Two tips in the advice block point at manual
work: requests you keep retyping and short "continue"-style nudges. An optional --break-check hook
(UserPromptSubmit) reminds you to stand up after 90 minutes without a break.
Quick start
Nothing to install, nothing to clone:
uvx claude-usage-dashboard --open
pipx run claude-usage-dashboard --open does the same, and pip install claude-usage-dashboard
keeps it around. Or take a copy and run it in place:
git clone https://github.com/Thinkpload/claude-code-usage-dashboard
cd claude-code-usage-dashboard
python -m claude_usage_dashboard --open
Either way it scans your logs, writes ~/.claude/usage-report/, and opens the page. Scanning a
hundred sessions takes up to a minute; everything after that is instant. Run it again whenever you
want fresh numbers — the page is a plain file, there is no server and no daemon.
On Windows, run it once with --register-refresh and the page gets a refresh button: it opens a
claude-usage:// link that rebuilds it in the background from the logs touched since the last build
(a few seconds), shows the progress under the button, and reloads the page when the new build lands
(the browser asks the first time). Register from a pip install or a checkout — a
uvx/pipx run copy lives in a temporary environment the link would outlive.
Python 3.9+, standard library only. Windows, macOS and Linux.
Make the weekly limit real
Anthropic does not publish limits in tokens, so any tool claiming to know your exact remaining quota
is guessing. This one calibrates itself against the real /usage figure instead.
On every run it fetches that figure the same way Claude Code's own /usage panel does: with your
login token from ~/.claude/.credentials.json, sent to api.anthropic.com and nowhere else. The
token is never printed or copied anywhere new. What gets recorded is the "all models" percentage,
the Fable percentage, the moment the week resets, the 5-hour window with its own reset, and the
cloud-session credit when there is one. A rerun within the hour replaces the last reading rather
than adding another.
If you would rather it never touched the token, run with --no-fetch and feed the reading yourself
from claude.ai → Settings → Usage (or /usage in Claude Code):
claude-usage-dashboard --observe 46 --fable 31 --reset "2026-09-17 20:00"
This is the beginning of the README. Read the rest at the original. Read the full README ↗
