claude-rank

Gamified Claude Code usage tracker. See your level, stats, achievements, prestige stars, streaks, and live rate limit bars -- all from the terminal.

  _____ _                 _        __  __      _
 / ____| |               | |      |  \/  |    | |
| |    | | __ _ _   _  __| | ___  | \  / | ___| |_ ___ _ __
| |    | |/ _` | | | |/ _` |/ _ \ | |\/| |/ _ \ __/ _ \ '__|
| |____| | (_| | |_| | (_| |  __/ | |  | |  __/ ||  __/ |
 \_____|_|\__,_|\__,_|\__,_|\___| |_|  |_|\___|\__\___|_|

  LEVEL 8 - MODEL MAESTRO  ★★
  Streak: 14d 🔥 (best: 14d)

  ████████████████████████░░░░░░░░░░░░  67% to Lv.9
  1.68B / 2.50B tokens

  5h:   ████████████░░░░░░░░░░░░░░░░ 44%  ↻ 3h 12m
  7d:   ████████████████████░░░░░░░░ 72%  ↻ 4d 8h

  ACHIEVEMENTS
  ├─ * Billion Token Club
  ├─ ~ Century Sessions
  └─ + Marathon (28h session)

Install

# Run directly with npx (no install needed)
npx claude-rank

# Or install globally
npm install -g claude-rank

Commands

claude-rank (or claude-rank show)

Full dashboard with your level, prestige stars, streak, stats, model breakdown, live usage bars, achievements, and a 30-day token sparkline.

claude-rank              # Full display with intro animation + live API data
claude-rank --no-live    # Skip the live API call
claude-rank --no-intro   # Skip the startup animation

claude-rank flex

Full-screen animated rank display. Big ASCII level number drops in, stats fly across the screen, XP bar fills up. Built for screenshots and flexing.

claude-rank flex

claude-rank usage

Just the live usage bars (5-hour, 7-day, and Opus-specific windows).

claude-rank usage

claude-rank float

Persistent floating widget. Open a small terminal window, run this, and position it wherever you want on screen. Auto-refreshes.

claude-rank float              # Default 60s refresh
claude-rank float -i 30        # Refresh every 30 seconds

Controls:

• r - Manual refresh
• q / Esc / Ctrl+C - Quit

claude-rank prestige

Prestige system (like Call of Duty). When you hit Level 12 (The Chosen Prompt), you can prestige to earn a star. Stars appear on all displays.

claude-rank prestige

claude-rank leaderboard

Global anonymous leaderboard. Your account is identified by a hash (no personal info sent).

claude-rank leaderboard                    # View the leaderboard
claude-rank leaderboard --join myname      # Join with a username
claude-rank leaderboard --sync             # Sync your current stats

claude-rank history

Full daily token breakdown parsed from JSONL session logs. Shows input, output, cache read, cache write, messages, and sessions per day.

claude-rank history            # Last 60 days
claude-rank history -d 90      # Last 90 days

claude-rank levels

Show all 12 levels with thresholds and which one you've reached.

claude-rank levels

claude-rank stats

Raw aggregated stats dump (total tokens by type, model breakdown, session info).

claude-rank stats

claude-rank whoami

Show your Claude account email, plan, and org info.

claude-rank whoami

Level System

Your level is based on total tokens processed (input + output + cache creation + cache read):

| Level | Title | Threshold | |-------|-------|-----------| | 1 | Prompt Rookie | 0 | | 2 | Token Tinkerer | 500K | | 3 | Context Crafter | 5M | | 4 | Inference Initiate | 25M | | 5 | Neural Navigator | 75M | | 6 | Attention Adept | 200M | | 7 | Transformer Sage | 500M | | 8 | Model Maestro | 1B | | 9 | Token Titan | 2.5B | | 10 | Singularity Sovereign | 5B | | 11 | AGI Architect | 10B | | 12 | The Chosen Prompt | 25B |

Prestige

When you reach Level 12, you can run claude-rank prestige to earn a star (★). Stars appear next to your level on all displays. There's no limit to how many times you can prestige.

Streaks

Your daily activity streak is tracked automatically. Use Claude Code every day to keep it going. Streaks appear on your dashboard and can be synced to the leaderboard.

Achievements

Unlocked automatically based on your usage patterns:

• Billion Token Club - 1B+ total tokens
• 100M Token Veteran - 100M+ total tokens
• Century Sessions - 100+ sessions
• 500 Club - 500+ sessions
• 10K Messenger - 10,000+ messages
• Marathon - 10+ hour longest session
• Night Owl - 20+ late night sessions (10pm-4am)
• Month Streak - 30+ days active
• Multi-Model - Used 2+ different models

How It Works

Local Stats

Reads ~/.claude/stats-cache.json which Claude Code generates and maintains. This file contains aggregated token counts, daily activity, session history, and hourly usage distribution.

Session Logs (History)

For the history command, parses JSONL session files from ~/.claude/projects/*/ to get full per-day token breakdowns including cache reads and cache writes.

Live Usage (Rate Limits)

Calls the Anthropic OAuth usage API to fetch real-time utilization percentages for the 5-hour, 7-day, and Opus-specific rate limit windows.

Authentication is handled automatically:

• macOS: Reads from Keychain (Claude Code-credentials)
• Linux/other: Falls back to ~/.claude/.credentials.json

If auth fails, the tool still works -- you just won't see live usage bars.

State Persistence

Prestige level, streak data, and leaderboard username are stored locally at ~/.claude-rank/state.json.

Requirements

• Node.js 18+
• Claude Code installed and used at least once (so stats exist)

Privacy

This tool reads only local files and makes authenticated API calls to Anthropic's usage/profile endpoints (the same ones Claude Code uses). Leaderboard submissions are opt-in and identified by a SHA256 hash of your auth token -- no email, name, or personal data is sent.

License

MIT