Metadata-Version: 2.4
Name: stradiz-claude-tokens
Version: 1.0.1
Summary: Live terminal TUI tracking Claude Code token usage and cost estimates
Author-email: Bernardo Andreatta <bernardo.giraldi.andreatta@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Bernardo-Andreatta/terminal-claude-token-usage
Project-URL: Repository, https://github.com/Bernardo-Andreatta/terminal-claude-token-usage
Project-URL: Bug Tracker, https://github.com/Bernardo-Andreatta/terminal-claude-token-usage/issues
Keywords: claude,anthropic,token,tui,terminal,usage,cost
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# 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

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

### Windows — Scoop

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

> Requires [Scoop](https://scoop.sh) and Python installed (`scoop install python`).

### Linux — pipx

```bash
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

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

## Usage

```bash
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):

```bash
# ~/.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:

```bash
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.
