📊 claude-usage

What it shows

• Bar chart — daily aggregated cost (or token) usage scaled to max, with green bars and yellow values
• Summary line — session count, total cost, total tokens, and models seen
• Session table — date/time, git branch, duration, message and tool-call counts, tokens, cost, plus a bold totals row

How it works

Both tools are native binaries — no Python or other runtime required.

Setup

Quick install recommended

curl -fsSL https://raw.githubusercontent.com/bradmontgomery/claude-usage/main/install.sh | bash

irm https://raw.githubusercontent.com/bradmontgomery/claude-usage/main/install.ps1 | iex

Both scripts download the pre-built binaries for your platform, install the SessionEnd hook, and register it in ~/.claude/settings.json. Safe to re-run.

Manual setup (from source)

Requires Rust / cargo.

git clone https://github.com/bradmontgomery/claude-usage.git
cd claude-usage
make install-hook

make install-hook builds both binaries, copies them to ~/.local/bin/, and registers the SessionEnd hook in ~/.claude/settings.json. Make sure ~/.local/bin is on your PATH.

Pre-built binaries

Download the archive for your platform from the Releases page and extract both binaries (claude-usage and collect-session-stats) to somewhere on your PATH.

Then register the hook manually:

python3 hook/register.py /path/to/collect-session-stats

First run

Start (or finish) a Claude Code session to generate your first log entry, then:

claude-usage

Usage

claude-usage                        # last 30 days, cost chart
claude-usage --days 7               # last 7 days
claude-usage --chart tokens         # token chart instead of cost
claude-usage --chart tokens --days 14

Development

make build        # debug build (both binaries)
make release      # optimized build
make run          # cargo run claude-usage (pass args after --)
make check        # fast compile check, no binary produced
make install      # build + copy both binaries to ~/.local/bin
make install-hook # install + register the SessionEnd hook
make clean        # remove the target/ directory

Keeping pricing current

Token pricing is defined in src/collect_session_stats.rs in the model_price function. If Anthropic changes pricing, update the values there, rebuild with make install, and re-run make install-hook to re-register.

Models not in the pricing table are tracked but marked as unpriced — the CLI will show a warning when this happens.

Log format

Each line in ~/.claude/usage-log.jsonl is a JSON object:

{
  "session_id": "...",
  "recorded_at": "2026-05-05T12:00:00+00:00",
  "session_start": "2026-05-05T10:00:00Z",
  "session_end": "2026-05-05T11:00:00Z",
  "duration_ms": 3600000,
  "message_count": 42,
  "tool_call_count": 18,
  "git_branch": "main",
  "cwd": "/home/user/projects/myapp",
  "total_cost_usd": 0.2341,
  "models": {
    "claude-sonnet-4-6": {
      "input_tokens": 50000,
      "output_tokens": 8000,
      "cache_write_tokens": 12000,
      "cache_read_tokens": 30000,
      "cost_usd": 0.2341
    }
  },
  "unpriced_models": []
}