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)

Русская версия README

What it tells you

• 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."
• 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.

Quick start

Nothing to install, nothing to clone:

uvx --from git+https://github.com/Thinkpload/claude-code-usage-dashboard claude-usage-dashboard --open

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.

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 asks you instead.

Open claude.ai → Settings → Usage (or run /usage in Claude Code) and feed it what you see:

claude-usage-dashboard --observe 46 --fable 31 --reset "2026-09-17 20:00"

• --observe — the "all models" percentage for the current week
• --fable — the Fable percentage, which runs on its own separate budget
• --reset — when the week rolls over

From that one reading the tool solves for your plan's weekly budget in load units (tokens weighted by model and token type) and can then track every later week on its own. Give it a reading now and then; each one sharpens the estimate. Until you do, the gauge says so plainly instead of inventing a number.

Plan changes are handled per plan: a Max reading never gets rescaled into a Pro budget, because "Pro = Max ÷ 5" was tested against real weeks and does not hold.

How it counts

Run it at least monthly, or on a scheduler, or the pruning will outrun your history.

Configuration

Copy config.example.json to ~/.claude/usage-report/config.json and edit. The interesting keys:

--out-dir DIR points the whole thing at a different data directory, which is how the demo builds without touching anything of yours.

As a Claude Code skill

Copy or symlink the repo into ~/.claude/skills/claude-usage-report/ — SKILL.md is in the root, so the folder works as a skill as it stands. Then ask Claude Code "how much have I spent this month" or "refresh the usage dashboard" and it will run the script, read the numbers back to you, and publish the page as an artifact.

Making it yours

The page is one HTML file with no external scripts: it opens from file://, and it is equally happy as a claude.ai artifact. Mechanics and looks are deliberately separated — every colour and font lives in the :root block at the top of claude_usage_dashboard/template.html, and <div class="bg"> is left empty for whatever background you want.

• Hand dashboard.design.html (the same page on a small slice of data) to a design model, then python -m claude_usage_dashboard --adopt the-result.html puts the new look back into the template and keeps your data hooks intact. The old template is saved beside it as template.bak.html. Run that one from a checkout — an ephemeral uvx install has nowhere to keep the result.
• Or ignore the page entirely and build your own on top of data.json — the fields are documented in docs/data-contract.md.
• template.html is the English original; i18n/ru.json beside it is a flat map that rebuilds the Russian page from it. Adding a language means adding one such file.

How this compares to ccusage

ccusage is the well-known CLI in this space, and it is very good at what it does: fast per-session and per-day cost tables in your terminal.

This project is after something else:

• a visual page rather than a table — heatmaps, trends, a weekly instrument
• the weekly limit, calibrated from your own /usage readings, including Fable's separate scale
• history that survives Claude Code's 30-day log pruning
• project grouping into work and personal, with commits alongside the hours

Use both. They answer different questions.

Caveats

• Everything about the weekly limit is a model built on top of your /usage readings, not published data. The page marks uncalibrated figures as estimates rather than dressing them up.
• Skill cost counts only the re-reading of a skill's text out of cache; /usage counts more broadly.
• Your project names are in the report. Think before you put the rendered page somewhere public.

License

MIT