https://github.com/jayson-jia-dev/cc-token-status
Claude Code usage dashboard in your macOS menu bar — costs, tokens, plan limits, trends, multi-machine sync
https://github.com/jayson-jia-dev/cc-token-status
anthropic claude claude-code developer-tools macos menu-bar swiftbar token-usage usage-tracker
Last synced: 12 days ago
JSON representation
Claude Code usage dashboard in your macOS menu bar — costs, tokens, plan limits, trends, multi-machine sync
- Host: GitHub
- URL: https://github.com/jayson-jia-dev/cc-token-status
- Owner: jayson-jia-dev
- License: mit
- Created: 2026-04-08T13:07:35.000Z (18 days ago)
- Default Branch: main
- Last Pushed: 2026-04-11T11:27:47.000Z (15 days ago)
- Last Synced: 2026-04-12T07:02:36.681Z (15 days ago)
- Topics: anthropic, claude, claude-code, developer-tools, macos, menu-bar, swiftbar, token-usage, usage-tracker
- Language: Python
- Homepage: https://github.com/echowonderfulworld/cc-token-status#quick-install
- Size: 7.35 MB
- Stars: 5
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-claude-code-toolkit - cc-token-status - machine iCloud sync. 5 languages, dark/light mode. Single Python file, auto-updates | (Companion Apps & GUIs / GateGuard — Fact-Forcing PreToolUse Gate)
README
cc-token-status
Claude Code usage dashboard in your macOS menu bar.
Costs, plan limits, trends, user level — all in one click.
## Quick Install
```bash
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 |
| **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 + 30-min stale fallback)
- **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
- **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](https://platform.claude.com/docs/en/about-claude/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"}` | `{}` |
| `menu_bar_icon` | SwiftBar icon style | `"sfSymbol=sparkles.rectangle.stack"` |
## Update
Auto-updates daily with SHA256 verification. Manual update:
```bash
curl -fsSL https://raw.githubusercontent.com/jayson-jia-dev/cc-token-status/main/install.sh | bash -s -- --update
```
## Uninstall
```bash
curl -fsSL https://raw.githubusercontent.com/jayson-jia-dev/cc-token-status/main/uninstall.sh | bash
```
## Requirements
- macOS
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)
- Python 3.8+
- [SwiftBar](https://github.com/swiftbar/SwiftBar) (auto-installed)
## License
MIT