A beautiful TUI for tracking your Claude Code token usage. Automatically logs token consumption after each response and provides an interactive dashboard to analyze your usage patterns.

• Automatic Logging - Hooks into Claude Code to log tokens after each response
• Per-Model Breakdown - Track usage separately for Opus, Sonnet, and Haiku
• Detailed Token Types - Input, Output, Cache Read, and Cache Write tracked separately
• Interactive Date Picker - View stats for any date range
• Auto-Refresh - Live updates every 2 seconds
• Daily Trends - Sparkline graphs and mini bar charts
• Zero Dependencies - Pure Python, no external packages required

git clone https://github.com/yourusername/claude-token-stats.git
cd claude-token-stats
./install.sh

1. Copy hooks/log-token-stats.py to ~/.claude/hooks/
2. Copy bin/claude-stats to ~/.claude/hooks/
3. Add to ~/.claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/log-token-stats.py"
          }
        ]
      }
    ]
  }
}

4. Add alias to your shell rc file:

alias claude-stats="~/.claude/hooks/claude-stats"

claude-stats        # Open interactive TUI
claude-stats -h     # Show help

Stats are stored as JSON in ~/.claude/stats/YYYY-MM-DD.json:

{
  "date": "2024-01-15",
  "sessions": [...],
  "daily_totals": {
    "input_tokens": 1234,
    "output_tokens": 5678,
    "cache_read_tokens": 90123,
    "cache_creation_tokens": 4567,
    "total_tokens": 101602,
    "request_count": 42,
    "session_count": 3
  },
  "by_model": {
    "claude-opus-4-5-20251101": {...},
    "claude-sonnet-4-20250514": {...}
  }
}

./uninstall.sh

This will:

• Remove hook scripts
• Remove the PostToolUse hook from settings
• Remove shell alias
• Optionally delete your stats data

1. PostToolUse Hook - Claude Code triggers the hook after each tool use
2. Transcript Parsing - The hook reads the session transcript JSONL file
3. Token Extraction - Extracts usage data from each API response
4. Aggregation - Aggregates by model and saves to daily JSON file
5. TUI Display - The viewer reads JSON files and renders the dashboard

• Python 3.8+
• Claude Code CLI
• macOS or Linux (uses termios for keyboard input)

MIT

PRs welcome! Please open an issue first to discuss major changes.