stradiz-claude-tokens 1.0.1

Live terminal TUI tracking Claude Code token usage and cost estimates

claude-tokens

Live terminal TUI tracking Claude Code token consumption — session and weekly windows, cost estimates, progress bars, calibration wizard, and color picker. Cross-platform: Mac, Linux, Windows.

  ~ estimates only · Anthropic usage API is private
╭──────────────────────────────────────────╮
│   Tue 2026-05-20  14:32:01 Claude Tokens │
│                                          │
│   Session  resets in 2h 14m             │
│   ████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░  │
│   2.72M / 7.63M  (36%)                  │
│   4.91M remaining                        │
│   42 msgs  ≈ $1.23                       │
│                                          │
│   Week  resets Tue 05/26 12:00           │
│   ████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  │
│   6.78M / 26.23M  (26%)                 │
│   19.45M remaining                       │
│   187 msgs  ≈ $5.67                      │
│                                          │
╰──────────────────────────────────────────╯
  refresh 15s · q quit · r refresh · c calibrate · t colors

Install

Mac — Homebrew

brew tap Bernardo-Andreatta/tap
brew install claude-tokens

Windows — Scoop

scoop bucket add bernardo https://github.com/Bernardo-Andreatta/scoop-bucket
scoop install claude-tokens

Requires Scoop and Python installed (scoop install python).

Linux — pipx

pipx install git+https://github.com/Bernardo-Andreatta/terminal-claude-token-usage.git

pipx isolates the install and ensures claude-tokens lands in your PATH automatically. Install pipx: sudo apt install pipx · sudo pacman -S python-pipx · pip install pipx

Any platform — from source

git clone https://github.com/Bernardo-Andreatta/terminal-claude-token-usage.git
cd terminal-claude-token-usage
pipx install .

Usage

claude-tokens            # interactive TUI
claude-tokens-calibrate  # standalone calibration wizard
claude-tokens-colors     # standalone color picker
python -m claude_tokens  # same as claude-tokens, via module

Keys: q quit · r force refresh · c calibrate limits · t pick colors

Configuration

Settings are saved to ~/.claude/claude-tokens.conf — the calibration wizard and color picker both offer to save there automatically. No shell editing required.

You can also set any value as an env var (env vars override the config file):

# ~/.claude/claude-tokens.conf  (or export in ~/.zshrc / $PROFILE)
CLAUDE_SESSION_LIMIT=7631489
CLAUDE_WEEKLY_LIMIT=26230769
CLAUDE_REFRESH=15

Calibrating limits

Press c in the TUI (or run claude-tokens-calibrate standalone) while claude.ai shows your current usage percentages. The tool reads your current token counts, prompts for the percentages shown on claude.ai → Settings → Usage, and calculates limits automatically.

  Session usage % shown on claude.ai: 36
  Weekly  usage % shown on claude.ai: 26

  CLAUDE_SESSION_LIMIT = 7,550,583  (7.55M)
  CLAUDE_WEEKLY_LIMIT  = 26,076,923  (26.08M)

Limits apply immediately in the running TUI. The wizard then prompts to save to ~/.claude/claude-tokens.conf.

Colors

Press t in the TUI (or run claude-tokens-colors standalone) to open the interactive color picker. Choose warning color behavior, pick a color per role from 16 swatches, and preview the full widget live.

Color roles can also be set directly as env vars:

CLAUDE_COLOR_SESSION=cyan      # session section (default: cyan)
CLAUDE_COLOR_WEEK=magenta      # week section (default: magenta)
CLAUDE_COLOR_OK=green          # remaining indicator, low usage (default: green)
CLAUDE_COLOR_WARN=yellow       # bar/remaining at 75%+ usage (default: yellow)
CLAUDE_COLOR_CRIT=red          # bar/remaining at 90%+ usage (default: red)

Accepts color names (cyan, bright_cyan, magenta, …) or raw ANSI codes (36, 35, 92, …).

All env vars

Variable	Default	Description
CLAUDE_SESSION_LIMIT	0	Session token limit (0 = no bar cap)
CLAUDE_WEEKLY_LIMIT	0	Weekly token limit (0 = no bar cap)
CLAUDE_REFRESH	15	Refresh interval in seconds
CLAUDE_SESSION_OFFSET_SECS	0	Shift session start earlier (useful when starting on claude.ai web)
CLAUDE_WEIGHT_CACHE_READ_SESSION	0.1	Cache read weight for session quota
CLAUDE_WEIGHT_CACHE_READ_WEEKLY	0.0	Cache read weight for weekly quota
CLAUDE_PRICE_INPUT	3.00	Input token price per 1M
CLAUDE_PRICE_OUTPUT	15.00	Output token price per 1M
CLAUDE_PRICE_CACHE_WRITE	3.75	Cache write price per 1M
CLAUDE_PRICE_CACHE_READ	0.30	Cache read price per 1M
CLAUDE_MARGIN	2	Left margin spaces in the TUI
CLAUDE_WARN_COLORS	1	Set to 0 to disable warning color shifts

How it works

Reads ~/.claude/projects/**/*.jsonl — the JSONL logs Claude Code writes per conversation. Aggregates usage fields from API response records, deduplicating by message ID to avoid double-counting.

Session window: detected by simulating 5-hour windows through the last 12 hours of activity. A new session opens whenever an event arrives after the previous 5-hour window has closed — matching claude.ai's fixed session model.

Weekly window: resets Tuesday 15:00 UTC (matching claude.ai's observed reset schedule).

Cache read accounting: session and weekly quotas use different weights. Session counts cache reads at ~10%; weekly ignores them. If your percentages drift from claude.ai, run c to recalibrate.