A tiny native macOS menu bar app that shows your
Claude Code usage at a glance — session limit, weekly
limits, and today's estimated token cost — without opening Claude Code and
typing /usage.
Fully native: Swift + AppKit/SwiftUI, built with SwiftPM, zero external dependencies and no telemetry.
In the menu bar: a small gauge that fills as you use your 5-hour session quota, tinted along a heat scale (green → yellow → orange → red), with the used percentage next to it.
In the panel (click the gauge):
- Session · 5 hours — used %, progress bar, and a "resets in 2h 14m" countdown
- Weekly · all models — plus a separate bar for every model-scoped weekly limit the API reports (e.g. Fable), exactly like Claude's own usage screen
- Today — per-model token totals and estimated cost, computed locally from your
~/.claude/projects/**/*.jsonltranscripts - A status dot in the header shows connection health: green = data fresh, yellow = temporary issue (last good data stays on screen), red = error. Hover it for details.
- Settings: refresh interval (1 – 10 min), language (auto / Türkçe / English), launch at login
The panel language follows your system locale by default and can be switched manually.
Download the latest .dmg from the
Releases page, open
it, and drag ClaudeMeter.app to /Applications.
Release artifacts are not code-signed with an Apple Developer ID or notarized — they are only ad-hoc signed by the build script. Gatekeeper may say the developer can't be verified, or even that the app "is damaged", because of the quarantine flag macOS adds to downloaded files. Either allow it via System Settings → Privacy & Security → "Open Anyway", or clear the flag in Terminal:
xattr -cr /Applications/ClaudeMeter.appBuilding from source on your own machine (below) triggers no such warning, since there is no quarantine flag to clear.
Requires Xcode / Swift toolchain (macOS 14+, Apple Silicon).
swift test # run the test suite (ClaudeMeterCore)
bash scripts/package.sh # → dist/ClaudeMeter.app and dist/ClaudeMeter_<version>_aarch64.dmgscripts/package.sh builds a release binary (swift build -c release),
assembles dist/ClaudeMeter.app, ad-hoc code-signs it, and wraps it in a
.dmg — the same steps CI runs on every push.
| Piece | Source | Notes |
|---|---|---|
| Limit percentages | Anthropic's OAuth usage endpoint (api.anthropic.com) |
The same source Claude Code's /usage screen uses |
| Credentials | macOS Keychain (security CLI), falling back to ~/.claude/.credentials.json |
Read once at startup, re-read only on 401 |
| Today's tokens/cost | Local JSONL transcript scan with message de-duplication | Cost is an estimate from a built-in price table |
The OAuth token lives only in memory — never written to disk, never
logged, and sent to nothing but api.anthropic.com over HTTPS. Once a day
the app also asks api.github.com for the latest release tag (version
metadata only, no credentials attached) to show an update notice. Those are
the app's only two network destinations. There is no analytics or telemetry
of any kind.
- Claude Code installed and signed in on the same machine (the app reads its credentials; it never asks for your password).
- macOS 14 (Sonoma) or later, Apple Silicon.
On first launch macOS will ask for permission to read the "Claude Code-credentials" Keychain item — choose Always Allow.
Available from the panel: refresh interval (1, 2, 5, or 10 minutes),
language (auto / Türkçe / English), and "Launch at login" (registered via
SMAppService, macOS's login-item API).
Usage data refreshes on the chosen interval and via the panel's Refresh button (15 s cooldown). Opening the panel deliberately does not fire a request, so peeking at your stats never counts against the API's rate limit.
The app checks GitHub's Releases API once a day for a newer version tag. When one exists, a blue notice appears at the top of the panel — "Version vX.Y.Z is available — click to download" — and clicking it opens the latest-release page. Updating is manual:
- Download the new
.dmgfrom the release. - Install it over the existing app (open the
.dmg, drag to Applications). Settings are stored inUserDefaultsand survive the update. - Remember the unsigned-build step above for the fresh download.
The check fails silently (offline, rate limit, private repo — while the
repository is private the API returns 404, so the notice effectively
activates once the repo is public). For manual end-to-end testing the
endpoint can be overridden with the CLAUDEMETER_RELEASES_API environment
variable.
# 1. bump the version in Resources/Info.plist:
# CFBundleShortVersionString → X.Y.Z
# 2. commit, then tag and push:
git tag vX.Y.Z && git push origin main vX.Y.ZThe tag push triggers CI, which builds the .dmg and publishes a GitHub
Release with it attached. Running apps show the update notice on their next
daily check.
Quit from the panel, delete ClaudeMeter.app, and optionally remove
~/Library/Preferences/com.kadiraydinli.claudemeter.plist (settings) and the
login-item entry if "Launch at login" was enabled (toggle it off first, or
remove it in System Settings → General → Login Items).
- The usage endpoint is not officially documented; the parser is deliberately tolerant and verified against live responses. If Anthropic changes the response shape, the panel shows a parse notice and keeps the last known data.
- A 429 ("server busy") is normal under heavy account use; the app backs off and retries on the next tick. Refresh requests are throttled client-side as well.
- This is an unofficial personal tool, not affiliated with or endorsed by Anthropic. Cost figures are estimates.
MIT — provided "as is", without warranty of any kind; the authors accept no liability for any use of this software.