claude-token-widget

A statusline widget for Claude Code that shows token usage, context window, and rate limit countdowns directly in the CLI interface.

📊 47k in · 3k out  ██░░░░░░░░ 23%
⏱  ctx ░░░░░░░░░░ 4%  |  7d ██████░░░░ 61%  → 3d 14h

What it shows

Line 1 — Tokens + 5-hour rate limit

• Tokens sent (in) and received (out)
• 5-hour rate limit usage bar + percentage (matches the usage shown in the Claude UI)

Line 2 — Context + 7-day rate limit

• Context window usage bar + percentage (how much of the 200k token window is used in the current conversation)
• 7-day usage bar + percentage + countdown to weekly reset

Requirements

• Claude Code installed
• bash, jq, python3 (standard on Linux/macOS)

Installation

git clone https://github.com/your-username/claude-token-widget
cd claude-token-widget
bash install.sh

This symlinks the script to ~/.claude/statusline.sh and updates ~/.claude/settings.json automatically.

With BRL currency (optional)

bash install.sh BRL 5.75

Show cost in the statusline

By default, cost is hidden. To show it:

bash install.sh --show-currency         # USD
bash install.sh BRL 5.75 --show-currency  # BRL

Output with cost enabled:

📊 47k in · 3k out  ██░░░░░░░░ 23%  R$0.81
⏱  ctx ░░░░░░░░░░ 4%  |  7d ██████░░░░ 61%  → 3d 14h

Customization

All visual settings are at the top of statusline.sh:

# ── CORES (edite aqui) ───────────────────────────────
COLOR_OK='\033[32m'      # verde  — uso < 60%
COLOR_WARN='\033[33m'    # amarelo — 60–85%
COLOR_CRIT='\033[31m'    # vermelho — > 85%

# ── THRESHOLDS (edite aqui) ──────────────────────────
THRESHOLD_WARN=60
THRESHOLD_CRIT=85

# ── BARRA DE PROGRESSO (edite aqui) ──────────────────
BAR_FILLED='█'
BAR_EMPTY='░'
BAR_WIDTH=10

After editing, the statusline updates on the next message — no restart needed.

How it works

Claude Code runs the script after each assistant message and pipes a JSON object to stdin. The script extracts token counts, percentages, and rate limit timestamps, formats them with ANSI colors and Unicode progress bars, and prints two lines to stdout.

No API calls are made. The script is stateless and runs locally.

Uninstall

Remove the statusLine key from ~/.claude/settings.json and delete ~/.claude/statusline.sh.

License

MIT