cc-token-status

Claude Code usage dashboard in your macOS menu bar.
Costs, plan limits, trends, user level — all in one click.

  

Quick Install

curl -fsSL https://raw.githubusercontent.com/jayson-jia-dev/cc-token-status/main/install.sh | bash

No dependencies to install manually. SwiftBar is auto-installed if missing.

Why cc-token-status?

	cc-token-status	CLI tools	Web dashboards
See limits at a glance	Menu bar, one click	Run a command	Open browser
Official plan limits	5h/7d from Anthropic API	Most don't have	Some have
Burn rate warning	Auto-alert when approaching limit	No	No
Multi-machine sync	iCloud, zero config	No	No
Install effort	One command, no server	npm/pip install	Docker + server
User level system	5-dimension scoring	No	No

Features

Feature	Description
Plan Usage Limits	Live 5h session & 7d weekly quotas with color-coded progress bars (Session/Weekly/Sonnet/Opus/Extra)
Burn Rate Alert	Warns when session pace projects to hit rate limit within 30 minutes
Cost & Token Overview	API-equivalent cost, session count, total tokens with input/output/cache breakdown
Today + Trend	Today's spending with trend vs 30-day active-day average (↑12% when above average)
Subscription ROI	How much your Pro/Max/Team plan saves vs API pricing, with daily/monthly projections
User Level	🌑→🌒→🌓→🌔→🌕→👑 rank with progress bar and upgrade hints
Visual Dashboard	Click to open 12-panel ECharts report in browser: cost trend, model distribution, hourly activity, project ranking, token composition, rate limit gauges, machine comparison, daily detail table
Daily Details	Full cost history (newest first, older dates collapsible)
Model Breakdown	Per-model usage (Opus / Sonnet / Haiku) with percentages
Hourly Activity	Sparkline charts: ▅▇██▇▄ shows which hours you're most active
Project Ranking	Which projects consume the most tokens
Multi-Machine Sync	iCloud Drive auto-sync across Macs — zero config
Usage Alerts	macOS notifications at 80% and 95% for Session/Weekly/Sonnet/Opus limits
Extra Usage	Shows extra usage gauge with spent amount, monthly limit, and on/off status when enabled
Auto-Update	SHA256-verified updates from GitHub, checks daily
5 Languages	EN, 中文, ES, FR, 日本語 — auto-detected from system
Dark & Light Mode	Adapts color scheme to macOS appearance

User Level System

Multi-dimension scoring based on your Claude Code usage maturity:

🌑 Lv.1  Starter      练气期
🌒 Lv.2  Planner      筑基期
🌓 Lv.3  Engineer     金丹期
🌔 Lv.4  Integrator   元婴期
🌕 Lv.5  Architect    化神期
👑 Lv.6  Orchestrator 大乘期

Scored across 5 dimensions (100 points total):

• Usage depth — median session length, activity density
• Context management — CLAUDE.md, memory system, rules
• Tool ecosystem — MCP servers, plugins (work tools discounted)
• Automation — self-built commands, hooks, skills (framework installs weighted at 30%)
• Scale — substantial projects, worktrees, tenure

How It Works

┌─────────────────────────────────────────────────────────────┐
│  SwiftBar (5-min refresh)                                   │
│   ↓                                                         │
│  cc-token-stats.5m.py                                       │
│   ├─ scan()        → parse ~/.claude/projects/**/*.jsonl    │
│   │                  (incremental: mtime fingerprint cache)  │
│   ├─ get_usage()   → Anthropic OAuth API (4-min cache)      │
│   │                  ↳ macOS Keychain → OAuth token          │
│   ├─ save_sync()   → write to iCloud Drive                  │
│   ├─ auto_update() → GitHub + SHA256 verify                 │
│   └─ check_and_notify() → macOS notifications               │
└─────────────────────────────────────────────────────────────┘

• Token & cost — scans Claude Code JSONL session logs with incremental caching (only re-parses changed files), calculates API-equivalent cost with official Anthropic pricing
• Plan limits — reads OAuth token from macOS Keychain, queries api.anthropic.com/api/oauth/usage with smart caching (4-min fresh + 2-hour stale fallback, HTTP 429 graceful degradation)
• Auto-update — downloads new versions from GitHub, verifies SHA256 checksum before replacing plugin file
• Multi-machine sync — writes stats to iCloud Drive, reads other machines' data automatically
• Dashboard — generates self-contained HTML with embedded ECharts, opens in browser (12 panels, all data from local caches)
• Refresh — SwiftBar executes the plugin every 5 minutes

Pricing

Model	Input	Output	Cache Write (1h)	Cache Read
Opus 4.5 / 4.6	$5	$25	$10	$0.50
Sonnet 4.5 / 4.6	$3	$15	$6	$0.30
Haiku 4.5	$1	$5	$2	$0.10

USD per 1M tokens. Official pricing

Configuration

Edit ~/.config/cc-token-stats/config.json or use the in-app Settings menu:

Key	Description	Default
subscription	Monthly plan cost in USD	0
subscription_label	"Pro", "Max", "Team"	""
language	"auto", "en", "zh", "es", "fr", "ja"	"auto"
notifications	Usage limit alerts	true
auto_update	Daily update check	true
sync_mode	"auto" / "off"	"auto"
machine_labels	Custom device names, e.g. {"RL001":"Office"}	{}

Update

Auto-updates daily with SHA256 verification. Manual update:

curl -fsSL https://raw.githubusercontent.com/jayson-jia-dev/cc-token-status/main/install.sh | bash -s -- --update

Uninstall

curl -fsSL https://raw.githubusercontent.com/jayson-jia-dev/cc-token-status/main/uninstall.sh | bash

Requirements

• macOS
• Claude Code
• Python 3.8+
• SwiftBar (auto-installed)

License

MIT