Claude Code Usage Widget

A native macOS menu bar widget for tracking your Claude Code rate-limit usage in real time.

Stop guessing how much of your 5-hour session is left, or whether you're about to hit the weekly Sonnet cap mid-task. Click the menu bar icon, see every bucket at a glance, get back to coding.

Why

Anthropic shows your usage on a settings page buried two clicks deep. If you live in Claude Code, you want it where you already look — your menu bar — without launching a browser, polling in the background, or storing your credentials anywhere.

This widget is:

• Zero-config — uses your existing Chrome login, no API keys, no setup
• Private — reads cookies locally, talks only to claude.ai, stores nothing
• Native — Tauri + Rust, ~10 MB, no Electron, no background daemon
• Honest — open source, MIT, ~500 lines you can audit in five minutes

Features

• 🎯 All three rate-limit buckets — current 5-hour session, weekly all-models, weekly Sonnet-only
• 🚦 Color-coded progress bars — blue → orange (75%+) → red (90%+)
• ⏱️ Reset countdowns — know exactly when each bucket clears
• 🌓 Auto light/dark mode — follows macOS system appearance
• 🔋 Zero background activity — only fetches when you click the icon
• 🪶 Tiny footprint — ships as a single ~10 MB .app

Install

Option 1 — Download the prebuilt app (recommended)

Grab the latest .dmg from Releases, drag to /Applications, launch.

First launch: right-click the app → Open (the build is unsigned; this only happens once).

Option 2 — Build from source

Requires Rust and Node.js 18+.

git clone https://github.com/TN0123/claude-code-usage-widget.git
cd claude-code-usage-widget
npm install
npm run tauri:build

Output: src-tauri/target/release/bundle/macos/Claude Code Usage.app

Requirements

• macOS (the menu bar + NSPanel integration is macOS-only)
• Google Chrome with an active claude.ai session

How It Works

The widget reads your claude.ai session cookies from Chrome's local cookie database (read-only, via a temp copy) and queries the Claude usage API with them. Nothing is cached, transmitted to third parties, or persisted to disk.

Resource	Why	How
Chrome cookies DB	Read claude.ai session cookies	Copies to temp file, reads, deletes temp file
macOS Keychain	Decrypt Chrome's cookie encryption key	security find-generic-password (may prompt once)
claude.ai/api/…/usage	Fetch your usage data	Authenticated with your existing browser session

It does NOT:

• Store, log, or cache credentials
• Send data to any server other than claude.ai
• Run in the background or poll on a timer
• Modify any Chrome data

The full networking + cookie code is in src-tauri/src/ — about 400 lines.

Usage

1. Launch the app — a small icon appears in your menu bar
2. Click the icon to see your usage
3. Click anywhere else to dismiss
4. If you see an error, make sure you're logged into claude.ai in Chrome

Troubleshooting

"No sessionKey cookie found"

Log into claude.ai in Google Chrome and click Retry.

"Chrome cookies database not found"

The app expects Chrome at the default install location. If you use a non-standard path, open an issue.

"Could not read Chrome Safe Storage from Keychain"

The app needs Keychain access to decrypt Chrome's cookies. Allow the prompt, or grant access in System Settings → Privacy & Security → Keychain.

"Cloudflare blocked the request"

Wait a moment and click Retry. Happens occasionally with rapid requests.

Panel doesn't appear

Quit and relaunch. If it persists, check that the app has accessibility permissions in System Settings.

FAQ

Does this work with Firefox / Safari / Arc / Brave? Not yet — only Chrome's cookie store is supported. PRs welcome (see Contributing).

Does this work on Windows or Linux? No — menu bar + NSPanel are macOS-only. The cookie + API logic is portable, so a tray-icon port is feasible.

Will Anthropic ban me for using this? The widget hits the same /api/.../usage endpoint your browser hits when you open the usage settings page. It uses your real session — no scraping, no automation tricks.

Why Chrome and not the Claude API directly? The Anthropic API doesn't expose Claude Code rate-limit usage. The web app does, via your session. So we use the session.

Tech Stack

• Tauri v2 — native app shell
• tauri-nspanel — macOS NSPanel for menu bar behavior
• Vanilla HTML/CSS/JS frontend (no framework)
• Rust backend for cookie extraction and API calls

Development

npm run tauri:dev

Starts Vite + Tauri in dev mode with hot reload.

Contributing

Issues and PRs welcome — especially:

• Firefox / Safari / Arc cookie store support
• Windows / Linux tray-icon port
• Additional bucket visualizations
• Bug reports with steps to reproduce

For larger changes, open an issue first to discuss the approach.

License

MIT © Tanay Naik