claude-usage

What it is

Claude Code Usage Dashboard is a local-dashboard tool that reads Claude Code usage logs from the user's machine and presents charts and cost estimates. It operates as a web app (python cli.py dashboard) and as a VS Code extension, showing token usage, models, sessions, and projects.

How it works

The tool reads one JSONL file per session stored under ~/.claude/projects/. Each line is a JSON record; fields include message.usage.input_tokens, message.usage.output_tokens, and message.model. scanner.py parses these files and stores data in a SQLite database at ~/.claude/usage.db. dashboard.py serves a single-page dashboard on localhost:8080 with Chart.js charts and supports model filtering and a date-range dropdown. The dashboard can be configured with host/port via flags or environment variables.

Getting started

• Quick start commands include various installation approaches. Examples from README:

# macOS / Linux (Homebrew)
brew tap phuryn/claude-usage https://github.com/phuryn/claude-usage
brew install phuryn/claude-usage/claude-usage
claude-usage dashboard

# Any OS (uv tool / pipx)
uv tool install git+https://github.com/phuryn/claude-usage
claude-usage dashboard

# macOS / Linux (clone)
git clone https://github.com/phuryn/claude-usage
cd claude-usage
python3 cli.py dashboard

# Windows
git clone https://github.com/phuryn/claude-usage
cd claude-usage
python cli.py dashboard

# Docker
git clone https://github.com/phuryn/claude-usage
cd claude-usage
bash scripts/run-docker.sh

• The dashboard opens at http://localhost:8080 by default, with container runs exposing read-only transcripts and a SQLite database at ~/.claude/usage.db.

Recent releases

• v1.5.5 — 2026-07-10: Dashboard added an Est. Cost line overlay on the Daily Token Usage chart with a right-hand axis; includes a legend-toggleable line.
• v1.5.4 — 2026-07-01: Dashboard added a Title column to the Recent Sessions table and its CSV export; supports user-set custom-title via CLI.
• v1.5.3 — 2026-07-01: Packaging: Added pyproject.toml so the tool installs with uv tool or pipx (no clone required).
• v1.5.2 — 2026-07-01: Packaging: Updated Homebrew formula pin to v1.5.1 tag tarball for current sources.
• v1.5.1 — 2026-07-01: Packaging: Fixed Homebrew shim crash with Python 3.13; updated to modern Python kegs.

Traction

• 2123 stars, 391 forks, 20 open issues as of the provided data.

Behind the repo

• The repository includes a Python-based dashboard (dashboard.py), a scanner (scanner.py), and a CLI (cli.py). The project is licensed MIT and written in Python.

Caveats

• Requirements: Python 3.8+; no third-party packages (standard library only).
• Local data source: reads Claude Code usage logs from ~/.claude/projects/ and stores results in ~/.claude/usage.db.
• Not captured: cowork sessions (server-side transcripts are not written locally).