cc-token

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/main/install.sh | bash

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

Why cc-token?

Features

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.5m.py                                            │
│   ├─ ensure_cleanup_disabled() → patch cleanupPeriodDays → 99999 │
│   ├─ scan()        → parse ~/.claude/projects/**/*.jsonl         │
│   │                  (recurses into subagents/ — most parsers    │
│   │                   miss this and lose ~50% of history;        │
│   │                   msg.id dedup + TTL-aware pricing           │
│   │                   + incremental mtime fingerprint cache)     │
│   ├─ get_usage()   → Anthropic OAuth API (9-min fresh, 2h stale) │
│   │                  ↳ macOS Keychain → OAuth token              │
│   ├─ save_sync()   → write full state to iCloud Drive            │
│   ├─ load_remotes()→ trust other machines' written values        │
│   ├─ auto_update() → GitHub + SHA256 (24h throttle)              │
│   └─ check_and_notify() → one push per escalation, no spam       │
└──────────────────────────────────────────────────────────────────┘

• Session retention protection — before anything else, patches ~/.claude/settings.json so Claude Code's 30-day default auto-deletion can't wipe your cost history
• Token & cost — recurses ~/.claude/projects/**/*.jsonl so Task-tool subagent sessions (under subagents/) are counted, not silently dropped like in most parsers. Globally deduplicates by Anthropic msg.id so session resume/continue rewrites are counted once. Splits cache-write pricing by TTL (ephemeral_5m × 1.25 vs ephemeral_1h × 2 of input rate). Incremental mtime fingerprint cache only re-parses changed files
• Plan limits — reads OAuth token from macOS Keychain, queries api.anthropic.com/api/oauth/usage with smart caching (9-min fresh + 2-hour stale fallback, HTTP 429 graceful degradation)
• Rate-limit alerts — one notification per escalation per limit-type; state = {limit_key: {tier, at}} survives 5h/7d window rollovers so the same threshold doesn't re-fire. Burn-rate prediction suppressed once already blocked
• Auto-update — daily GitHub check with SHA256 verification, atomic tmp+rename, system proxy fallback, downgrade-protected; failures logged to ~/.config/cc-token/.update.log for diagnosis
• Multi-machine sync — writes full stats (including daily_models, daily_hourly, sessions_by_day) to iCloud Drive; reads peers' written values as-is (no re-pricing approximation) so header and Daily合计 stay exactly consistent
• 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

USD per 1M tokens. Official pricing

Configuration

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

Update

Three paths, same SHA256 verification and atomic replace:

1. Automatic — daily background check, no action needed (default)
2. Menu button — Settings → "Check for Updates Now" (bypasses the 24h throttle, shows result as a notification)
3. Reinstall script:

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

Stuck on an old version?

The dropdown title shows your current version (e.g. v1.5.18). If auto-update has silently failed for 3+ days, a ⚠️ appears in the title and you'll get a one-shot macOS notification. To force-repair from any state:

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

Update diagnostics live at ~/.config/cc-token/.update.log (rotated at 50 KB).

Versioning

Standard 3-segment SemVer:

• MAJOR — breaking config or behavior change
• MINOR — new user-facing feature (menu item, setting, dashboard panel)
• PATCH — bug fix or internal hardening

See Releases for per-version notes.

Uninstall

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

Requirements

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

License

MIT