claude-tracker

Real-time Claude Code usage monitor with predictions, streaks, achievements & smart alerts.

The #1 complaint about Claude Code: you hit the rate limit mid-task with zero warning. claude-tracker fixes that with a live dashboard showing your usage, burn rate, time remaining, and predicted limit hit time.

Quick Start

npx claude-tracker              # Live dashboard (refreshes every 5s)
npx claude-tracker status       # Quick one-shot snapshot
npx claude-tracker report       # 7-day history + cost summary
npx claude-tracker streak       # Your coding streak stats 🔥

Live Dashboard

  ◆ claude-tracker v2.0.0   14:32:01
  ────────────────────────────────────────────────────────────────────

  Plan: Pro   Tokens used this 5-hour window:

  ████████████████████░░░░░░░░░░░░░░░░░░░░  58%
  25,520 / 44,000 tokens

  ────────────────────────────────────────────────────────────────────

  Burn rate: 1,240 tok/min   Time left: 1h 8m   Reset in: 2h 41m   Est. cost: $0.0043

  ────────────────────────────────────────────────────────────────────

  Token breakdown:
  Input:     18,200
  Output:     7,320
  Cache:      4,100 (cache reads don't count toward limit)
  Sessions:   2     Model: claude-sonnet-4

  ────────────────────────────────────────────────────────────────────

  🔮 Predictions
  → At current rate: ~1h 8m of runway left
  → Efficiency: 40% output/input ratio

  🔥 Streak: 5 days
     On fire! 5-day coding streak!
     Best: 12 days  |  Total active: 47 days
     ■ ■ ■ ■ ■ □ ■ (last 7 days)

  🏅 Achievements
  👋 Hello World  💰 Token Miser  🦉 Night Owl  🎯 Cache Master  4/10

  Tips:
  → Over halfway. Consider batching remaining tasks into fewer sessions.

  Press Ctrl+C to exit   Refreshes every 5s

What Makes This Different

| Feature | claude-tracker | ccusage | claude-monitor | |---|:---:|:---:|:---:| | Real-time live dashboard | ✅ | ❌ | ✅ | | Predictive alerts ("limit in 47 min") | ✅ | ❌ | ❌ | | Streak tracking (daily gamification) | ✅ | ❌ | ❌ | | Achievement badges | ✅ | ❌ | ❌ | | Efficiency score (output/input ratio) | ✅ | ❌ | ❌ | | Smart scheduling suggestions | ✅ | ❌ | ❌ | | Zero dependencies | ✅ | ❌ | ❌ | | Terminal bell alerts | ✅ | ❌ | ✅ | | JSON output for scripting | ✅ | ✅ | ❌ | | Weekly report with cost estimate | ✅ | ✅ | ✅ |

Commands

| Command | What it does | |---|---| | claude-tracker | Live dashboard (default) — refreshes every 5s | | claude-tracker watch | Same as above | | claude-tracker status | One-shot snapshot, no live updates | | claude-tracker report | 7-day usage history + cost summary | | claude-tracker streak | Show your coding streak stats |

Options

| Option | Default | Description | |---|---|---| | --plan <n> | pro | Your Claude plan: free, pro, max5, max20 | | --warn <pct> | 75 | Alert threshold percentage | | --json | — | Output as JSON for scripting | | --compact | — | Minimal output for status bars |

Gamification

🔥 Streak System

Code with Claude daily to build your streak. The mini-calendar shows your last 7 days:

  🔥🔥🔥 Streak: 12 days
     Best: 15 days  |  Total active: 89 days
     ■ ■ ■ ■ ■ ■ ■ (last 7 days)

🏅 Achievements

| Badge | Name | How to unlock | |---|---|---| | 👋 | Hello World | First tracked session | | 💰 | Token Miser | Stay under 20% of limit | | ⚡ | Halfway There | Use exactly 50% of window | | 🏎️ | Limit Pusher | Hit 90%+ without going over | | 🦉 | Night Owl | Code after midnight | | 🐦 | Early Bird | Code before 7 AM | | 🔬 | Model Explorer | Use 2+ models in one window | | 🏃 | Marathon Coder | 4+ hour active session | | 👑 | Efficiency King | Output/input ratio above 0.5 | | 🎯 | Cache Master | Cache hit rate above 30% |

Token Limits (Approximate)

Community-reported estimates. Anthropic doesn't publish exact numbers.

| Plan | $/mo | ~Tokens per 5h window | |---|---|---| | Free | $0 | ~10,000 | | Pro | $20 | ~44,000 | | Max 5x | $100 | ~220,000 | | Max 20x | $200 | ~880,000 |

How It Works

Claude Code stores session data as JSONL files in ~/.claude/projects/. claude-tracker reads these files, filters to the current 5-hour rolling window, and aggregates token usage. No API calls, no accounts — purely local.

Zero Dependencies

Pure Node.js. No pip install, no virtual environments. Runs anywhere with Node 18+.

Related

• claude-md — Generate and audit CLAUDE.md files with gamification

License

MIT