MeterBar ships outside the Mac App Store. The app is not sandboxed — it must read other tools’ local logs and credentials. Install with Homebrew or download a notarized build from Releases.
A lightweight macOS menu bar app that monitors Claude Code, Codex CLI, xAI (Grok and Cursor),
OpenRouter, Kimi Code, Z.ai, GitHub Copilot, Muse Code, and Claude Console API credit at a glance — then tells you which provider still has
headroom, warns you before you hit a wall, and can resume your blocked sessions
by itself once a limit resets.
Screenshots
Screenshot generation and the separate website-asset publishing step are documented in the screenshot guide.
Features
Monitoring
- Menu Bar App: Quick access to usage data from your menu bar
- Per-Account Menu Bar Items: Give up to 4 Claude/Codex accounts their own status item, or use one merged item with an in-menu account switcher (Settings → General → Menu Bar Accounts)
- Multi-Service Support: Track Claude Code, Codex CLI, xAI (Grok and Cursor in one card), OpenRouter, Kimi Code, Z.ai GLM Coding Plan, GitHub Copilot, Muse Code, and Claude Platform (Console API credit)
- Provider Status: Service-health monitoring for every provider that publishes a status page, so you can tell a provider outage apart from your own exhausted quota
- Widget Support: macOS widget for at-a-glance monitoring
- Zero Configuration for CLI Providers: Reuses local CLI sign-ins without password entry
- Real-time Updates: Background refresh defaults to 10 minutes, with an opt-in 1–30 minute
adaptive cadence and prompt catch-up after wake
- Private Multi-Mac Sync: Opt in to combine daily usage, estimated cost, and shared quota state
across your Macs through your private iCloud database
- Pace-aware Bars: Usage bars show quota left with an expected-pace marker and burn-rate projection
- Color-coded Status: Green (healthy), Orange (tight), Red (critical/exhausted)
Automation
- Session Wake: Watch one Claude or Codex account and automatically resume its blocked sessions, one at a time, once the limit resets — the watcher keeps running after MeterBar quits (details)
- Fallback accounts: Optionally use the ordered Claude Code or Codex account list as a failover chain when the live account's primary quota is exhausted. MeterBar restores the preferred account after reset.
- Pre-limit Alerts: Two configurable thresholds — an early heads-up as a quota tightens, and a stronger alert as it runs out (details)
- Event Integrations: Run a local command or POST quota transitions to a webhook (details)
Cost and optimization
- Local Cost Scan: 30-day token spend computed from local session logs — nothing is uploaded unless you turn on the opt-in public profile
- Usage Tab: One reporting window over tokens and spend: a headline strip, a time series stackable by provider, token type or model, a breakdown by model, origin, project or provider with each row's input/output/cache mix, and an insights column that says what to trim and how far to trust the numbers
- What To Use Next: At the top of Limits, ranks which provider has the most headroom right now
- Display Currency: Keep USD as the default or choose EUR with daily ECB reference rates and an offline cache (Settings → Costs)
Scripting
- CLI Tool:
meterbar usage and meterbar cost, with a versioned --json schema (details)
- Local HTTP Endpoint:
meterbar serve exposes the same cached data read-only over loopback (details)
Supported Services
| Service | Auth Method | Metrics Tracked |
|---|
| Claude Code | Keychain OAuth token (/api/oauth/usage); CLI /usage fallback | 5h session, 7-day all models, 7-day Sonnet |
| Codex CLI | OAuth token from codex login | 5h limit, weekly limit, code review |
| OpenRouter | User-provided API key stored in Keychain | Account credits, spend, per-key limits |
| xAI | Cached grok login session (official CLI) plus Cursor's local database. One card, one weekly gauge | Shared weekly pool, reset time, extra credits; legacy Cursor accounts add their monthly pools and on-demand spend as extra rows |
| Kimi Code | Kimi Code's own sign-in file (read-only), or an API key stored in Keychain. Off until you enable it in Settings → Providers | 5-hour and weekly windows, monthly windows when the plan reports them, booster-wallet balance |
| Z.ai GLM Coding Plan | Coding Plan API key stored in Keychain; you choose the international (api.z.ai) or mainland (open.bigmodel.cn) region. Off until you enable it in Settings → Providers | 5-hour and weekly credit windows, monthly MCP tool allowance, and a peak / off-peak indicator |
| GitHub Copilot | Fine-grained token stored in Keychain, read through GitHub's documented billing API. Off until you enable it in Settings → Providers | A monthly budget bar only for organization-managed licences with a user-level budget (needs the billing role). Personal and legacy plans show their usage state — GitHub documents no allowance for them, so MeterBar does not guess one |
| Muse Code | Read-only Muse CLI sign-in (muse login). Off until you enable it in Settings → Providers. The first Connect may ask for Keychain access — choose Always Allow | Session and weekly windows when the account reports them. An idle 5-hour window is not shown as 0% |
| Claude Platform | Your Claude Console session: paste the Cookie header from a signed-in platform.claude.com request in Settings → Providers. MeterBar keeps only the sessionKey value in Keychain and sends it to alone; no browser cookie store is read. An API key cannot read billing, so it is not used. Off until you enable it. The cookie expires periodically and MeterBar asks for a fresh one when the Console rejects it |
Installation
Agent Install Prompt
Paste this into your local coding agent to have it install MeterBar for you:
Install MeterBar on this Mac. First verify this is macOS 26 or newer and that Homebrew is available. Install with: brew tap VincentShipsIt/tap && brew install --cask VincentShipsIt/tap/meterbar. If Homebrew is missing, ask before installing Homebrew. After installing, verify /Applications/MeterBar.app exists and that the meterbar CLI is linked, then open MeterBar. Do not ask me for API keys or paste secrets; for usage data, tell me to run claude login, codex login, and log into Cursor if I want those providers tracked.
Homebrew (Recommended)
brew tap VincentShipsIt/tap
brew install --cask VincentShipsIt/tap/meterbar
To update:
brew upgrade --cask VincentShipsIt/tap/meterbar
Homebrew installations continue to update through Homebrew. Direct-download builds from v1.7.1 onward can also use Settings → General → Software Update. Automatic checks are disabled until you explicitly opt in; Check Now always performs a one-time manual check.
Manual Download
Download the latest release from meterbar.dev.
Releases after v1.6.1 are Developer ID signed and notarized, so direct downloads open without Gatekeeper warnings. For v1.6.1 and earlier (ad-hoc signed only), right-click and select "Open" the first time, or run xattr -cr /Applications/MeterBar.app.
Starting with v1.7.1, direct-download releases include Sparkle 2 and consume an EdDSA-signed appcast.xml published with each GitHub Release. Older versions without Sparkle cannot discover v1.7.1 automatically and must be upgraded once manually.
Maintainer setup and release verification are documented in docs/sparkle-updates.md.
Build from Source
Prerequisites: macOS 26+, Xcode 26+
git clone https://github.com/VincentShipsIt/meterbar.dev.git
cd meterbar.dev
open MeterBar.xcodeproj
# Build and run (Cmd+R)
Setup
Claude Code
- Install Claude Code CLI:
npm install -g @anthropic-ai/claude-code
- Log in:
claude login
- The app reads usage from Claude Code's authenticated
/api/oauth/usage endpoint using its Keychain login (first launch shows a one-time Keychain access prompt); if no token is available it falls back to parsing claude /usage output
- Configure each Claude account in Settings with its own
CLAUDE_CONFIG_DIR. The unscoped default account can use the global Keychain token; any explicitly scoped account uses the CLI.
Codex CLI
- Install Codex CLI:
npm install -g @openai/codex
- Log in:
codex login
- Select your team/workspace when prompted
- The app automatically reads credentials from
$CODEX_HOME/auth.json (~/.codex/auth.json by default)
xAI (Grok and Cursor)
xAI tiers share one pool of AI usage across Grok and Cursor, refreshed weekly, so MeterBar shows a single xAI card. It reads two sources and merges them; either one is enough.
- Install Grok Build and log in:
grok login
- Optional: install and log into Cursor IDE. MeterBar reads Cursor's local database, so Cursor accounts on legacy monthly plans keep their "Cursor Models" / "Other Models" pools and on-demand spend as extra rows on the same card. For encrypted sign-ins, choose Connect Cursor in xAI settings and allow access to Cursor Safe Storage in Keychain. Background refresh never prompts, and decrypted credentials stay in memory. See Cursor credential access.
- Enable xAI under Settings → General → Tracked Providers
- MeterBar asks the official Grok CLI for weekly billing over ACP; that call has not been re-verified against a live merged-plan account. Usage-limit resets are read from grok.com with the cached login token (never logged), the same way Codex reset credits work.
meterbar usage --provider xai selects this card. The older --provider grok and --provider cursor tokens still work as aliases; JSON output always says xai. Settings saved before the merge (Grok or Cursor visibility, menu bar pins, widget choices) migrate to xAI automatically.
To track more than one Grok Build account, give each CLI login a distinct
GROK_HOME, then add that directory under Settings → Providers → xAI → Connection:
GROK_HOME=~/.grok-work grok login
GROK_HOME=~/.grok-personal grok login
The existing unscoped login remains the zero-configuration default profile
($GROK_HOME when already exported, otherwise ~/.grok). Each enabled profile
gets its own card, menu-bar account, widget entry, cache snapshot, refresh
result, and diagnostics check. A failed profile does not block the others.
Usage
- Launch the app - It appears in your menu bar with the tightest quota's percent left
- Click the icon - The popover shows every provider's quota windows
- Open the dashboard - Full view with limits, token costs, optimization, and settings
- Refresh - Click the refresh icon to update metrics
Understanding the Display
Each quota window shows the percent left, a pace marker for where usage
should be at this point in the window, reset countdowns, and — when a limit is
exhausted — a countdown to when usage resumes.
Status Colors
| Color | Meaning |
|---|
| Green | more than 25% of the quota left |
| Orange | 25% or less left - quota is tight |
| Red | 10% or less left - critical or exhausted |
Dashboard
| Tab | What it shows |
|---|
| Overview | Current health and local token history |
| Limits | Every tracked quota window, ranked by headroom |
| Usage | Where tokens and spend go, and how to trim them |
| Status | Provider service health |
| Diagnostics | Provider setup health |
| Share | Social card export |
Alerts
Settings → General → Notifications turns on threshold alerts, with two
independently configurable levels:
- Warn me — the first heads-up as a quota tightens
- Alert me — a stronger alert as the quota runs out
Both are off until you enable notifications. Disabled providers and stale data
never notify, repeat crossings are deduplicated rather than stacked, and an
alert only claims a quota is exhausted when it actually is — configuring the
critical level at "10% left" produces a warning at 10%, not a false
limit-reached banner.
Fallback accounts
Claude Code and Codex CLI can opt into automatic fallback from their provider
settings. The enabled account order is the chain: the first profile is
preferred, followed by each fallback. MeterBar identifies the live account from
the one profile mapped to the provider's canonical credential path; it never
infers the live account from list order. Missing or ambiguous mappings disable
automatic fallback until the profile layout is repaired.
MeterBar evaluates the chain only when the current refresh successfully reports
the live account's non-estimated primary window exhausted; cached data from a
failed fetch cannot trigger a switch, and it does not add another poll. For
Codex, the session window is primary when present, otherwise the provider's
weekly primary_window is used. Notification authorization is required before
a new automatic switch. Each successful switch posts a stable-id macOS
notification, and the live profile is marked in the menu-bar popover and
provider settings. Account-switch delivery to Event Integrations is explicitly
deferred and is not part of fallback-account acceptance; fallback switching
does not invoke the local-command or webhook lanes.
Automatic switching is available only when every enabled profile uses a
provider-owned credential file on the same volume. MeterBar exchanges those
files with macOS's atomic RENAME_SWAP operation, verifies the inode mapping,
and keeps a secret-free, atomically persisted recovery journal containing the
provider, account ids, paths, inode ids, and notification metadata only until
the switch notification is delivered. Startup recovery repairs interrupted
account metadata writes and retries an unacknowledged notification without
repeating the credential exchange.
After acknowledgement, a shared completed-state.json ledger durably retains
the provider, generation, current account UUID/location/path/inode snapshots,
and immutable path-to-authorized-UUID ownership history. A provider may
atomically replace an account's credential file; under the shared lock MeterBar
accepts the new inode only when the UUID, location, and normalized path are
unchanged. Release and debug builds use the ledger to prevent stale metadata
from repeating an exchange and to ensure a removed path cannot be reassigned to
a new account UUID. It contains neither credential bytes nor account display
names. Credential bytes are never copied into MeterBar storage or logs. Claude
Keychain and mixed
Keychain/file layouts are intentionally ineligible: Security.framework does
not provide an atomic multi-item transaction, so MeterBar refuses to risk a
partial credential exchange.
A request already in flight keeps the credential it started with and may fail;
its next CLI request uses the newly live account. The preferred profile is
restored once a later refresh observes its reset.
Session Wake
Settings → Automation watches a single Claude or Codex account and, once its
limit resets, automatically resumes the sessions that limit blocked — one at a
time, not all at once. A one-time confirmation explains this the first time you
turn it on.
The watcher runs as a launch agent, so it keeps working after you quit MeterBar.
Only one watcher runs at a time across the app and the CLI; a cross-process lock
prevents two from racing each other.
Cost Tracking
The Usage tab computes 30-day token spend by scanning your local Claude,
Codex, and Grok session logs. The scan is incremental and resumable — it caches
per-file results and picks up where it left off rather than re-reading the whole
corpus each time. Nothing is uploaded; the numbers are derived entirely from
files already on your disk.
Choose USD or EUR under Settings → Costs. USD is the default and
needs no conversion. When EUR is selected, MeterBar refreshes the official ECB
reference rate daily and keeps the last successful quote offline. The refresh
sends no usage or cost data; it only requests the ECB's public daily rate feed.
CLI Tool
MeterBar includes a command-line tool for scripts and automation.
# Show current usage
meterbar usage
# JSON output for scripts
meterbar usage --json
# Filter by provider (claude, codex, cursor, openrouter, grok, kimi, zai, copilot, muse-code, claude-platform)
meterbar usage --provider claude
# Show token costs from the app's last local scan
meterbar cost
# JSON output
meterbar cost --json
# Ask where a task should go: provider, account, model tier, fallbacks, and why.
# Recommendation only — reads cached usage and leaves work execution to you.
meterbar route --task implementation
meterbar route recommends Claude Code, Codex, xAI or OpenRouter from cached quota and health. Kimi Code, Z.ai, GitHub Copilot, Muse Code, and Claude Platform are tracked but return provider_unsupported when enabled; they never enter recommendations or fallbacks. Known hidden providers are omitted, and missing or unreadable configuration cannot enable the five newer providers. Route exits with 0 for a recommendation, 11 for a known capability, enablement, policy or quota restriction, 12 when every rejection is a data problem (or there are no candidates), and 13 for invalid input. See the CLI JSON contract.
meterbar cost reports the MeterBar app's cached 30-day scan (run one from
the app's Usage tab), so the CLI and the app always show the same numbers.
The --json schema is versioned for third-party integrations.
HTTP Endpoint
meterbar serve exposes the same cached data over a local HTTP endpoint, for
status bars, dashboards, and scripts that would rather poll a URL than shell out.
meterbar serve
# meterbar serve listening on http://127.0.0.1:47663
# Endpoints: GET /usage, GET /cost (Authorization: Bearer <token> required)
# Bearer token (generated, shown once): ...
The endpoint is read-only — it serves the cache and never triggers a provider
refresh or mutates state. It binds to loopback only unless you pass
--allow-remote, requires a bearer token on every request (generated and printed
once at startup if you do not supply --token), and rate-limits to 5 requests
per second per client address by default, so one noisy caller cannot starve
another.
--allow-remote exposes a plaintext HTTP listener on your network. The
bearer token and cached usage/cost data are not encrypted in transit, so use it
only on a trusted private network or place MeterBar behind a TLS-terminating
reverse proxy. Do not expose the listener directly to the public internet.
Event Integrations
Settings → General → Event Integrations can run a literal-argv local command or
POST quota transitions to a webhook. Both lanes and every event/provider/account
scope are off until explicitly enabled. The
versioned webhook contract documents the exact
payload, transition semantics, and outbound security boundary.
The CLI is automatically installed when using Homebrew. For manual installs, it's located at:
/Applications/MeterBar.app/Contents/Helpers/meterbar
How It Works
MeterBar reads usage data from local CLI output, local credential stores, and provider APIs:
macOS Keychain # Claude Code OAuth token (Claude Code-credentials)
claude /usage # Claude Code usage fallback (CLI output)
~/.claude/ # Claude Code account metadata and local sessions
$CODEX_HOME/auth.json # Codex CLI OAuth token (defaults to ~/.codex/auth.json)
~/Library/Application Support/Cursor/ # Cursor local DB (xAI card, legacy Cursor pools)
$GROK_HOME/auth.json # Grok CLI login (xAI weekly quota via ACP; resets via grok.com)
It then uses the respective local source or API to fetch current usage data:
- Claude Code (primary):
https://api.anthropic.com/api/oauth/usage, using the Claude Code-credentials Keychain OAuth token
- Codex:
https://chatgpt.com/backend-api/wham/usage
- xAI (Grok source): official
grok agent ACP _x.ai/billing for the weekly gauge; grok.com ConsumerUiSvc/GetRemainingResets for usage-limit resets
- Claude Platform (opt-in): read-only
GETs to platform.claude.com/api/organizations, …/prepaid/credits and …/current_spend with the pasted sessionKey cookie
Claude Code usage reads the authenticated /api/oauth/usage endpoint — the same data Claude Code's own /usage screen shows — because claude /usage no longer renders in a headless (non-interactive) spawn. Parsing the CLI output is kept as a fallback and can be forced by turning off "Claude Code OAuth usage" in Settings.
- Explicitly scoped Claude accounts are tracked by running
claude /usage with each account's configured CLAUDE_CONFIG_DIR (they have no profile-specific Keychain token of their own).
- xAI (Cursor source): Local SQLite queries
No provider API keys are required for CLI-backed services - the app reuses local Claude Code, Codex, and Grok sign-ins. The unscoped default Claude Code account's Keychain OAuth token is read to fetch usage (a one-time macOS Keychain prompt on first launch). Grok weekly quota still goes through the official CLI; the cached login token is used only for usage-limit resets and is never logged.
Privacy & Security
- All credentials remain in their original locations (managed by CLI tools)
- Cost figures are computed locally from session logs already on your disk; no log content leaves the machine
- Multi-Mac sync is off by default. When enabled, it sends compact daily rollups, coarse quota
windows/reset times, and deterministic hashes of provider account IDs to your private iCloud database.
It never sends raw account IDs, credentials, or log content.
- Public profile is off by default. When you turn it on (Share → Public profile), MeterBar
publishes each provider's quota windows and optional plan when its account ownership
is unambiguous, plus your 30-day token and session totals, top models, and daily tokens
for the last 7 days to a random
meterbar.dev/u/<id> link, and refreshes it while it is on.
Turning it off, or resetting the link, deletes the published copy. It never includes your name, email,
account names, folders, project names, or credentials (contract).
- No data is sent beyond providers' own usage endpoints by default. An explicitly
enabled webhook sends only the documented quota event fields to the URL the
user configured; credentials and config paths are never included.
meterbar serve is opt-in, read-only, loopback-bound by default, and token-gated.
--allow-remote is plaintext HTTP; use a trusted private network or a TLS proxy.- The main app is not sandboxed — it must read other tools' credential/log files
(
~/.claude, ~/.codex, Cursor's local database) and run the claude and grok binaries. The
widget extension is sandboxed. Hardened runtime is enabled for both.
- No analytics, telemetry, or crash reporting (the opt-in public profile above is the only feature that talks to a MeterBar host)
- Open source for full transparency
Architecture
- SwiftUI - Modern declarative UI
- Combine - Reactive data flow
- Hardened Runtime - Enabled for app and widget (the main app is un-sandboxed by
design so it can read local CLI credential/log files)
- URLSession - Native networking
Troubleshooting
"Not Connected" or "Not configured" for a service
Make sure you're logged into the CLI tool:
claude login # For Claude Code
codex login # For Codex CLI
grok login # For xAI (Grok Build)
If the app still shows "Not Connected" or "Not configured", re-run the login command. MeterBar treats expired local OAuth tokens as disconnected so it does not keep making failing usage requests.
Codex showing "Free" instead of Team
Run codex logout && codex login and select your team workspace when prompted.
App can't read credentials
The app reads CLI credential files from $CODEX_HOME/auth.json (~/.codex/auth.json by default), checks for the Grok CLI login, and reads Cursor's local database. If you built from source with App Sandbox enabled, those accesses will fail — the shipped configuration keeps the main app un-sandboxed for this reason.
Contributing
Contributions welcome! Please open an issue first to discuss changes.
License
MIT License - see LICENSE for details.
