UsageBar

English · 中文

A tiny edge bar that shows AI plan usage for Codex, Cursor, Grok, GLM, and optionally ZCode, Claude, Copilot, Gemini, and Antigravity. It reads local login state only, talks to each official API, and never sends your chats through a third-party server.

macOS 12+ · Windows · Linux · MIT License · Download latest

Changelog · Features · How usage and reset time are read · Install · Menu · FAQ · Privacy · License

Ring usage	Transparent icons

Codex	Cursor

Grok	GLM

Quota reset

Settings	Providers

Features

• The bar grows with the selection: 1–10 rings. Default: Codex, Cursor, Grok, GLM. Pick providers and their order from Providers…
• Hover for every window the vendor returns (5-hour, weekly, monthly / billing cycle, per-model, …) and the reset date/time in the system timezone. Codex, GLM, ZCode, and Grok also list banked reset cards and their expiry at the bottom of the card when the inventory is present. Expiry text turns yellow when a card has ≤ 1 day left, red when ≤ 8 hours
• When a window drops from a used percent back to 0%, that slot’s icon pulses green and a tooltip stays up; hover the card to reveal ×, click to dismiss
• A reset card also pulses that icon and pops a 30-second “expiring” card (1 day before, then once at 5 / 4 / 3 / 2 / 1 hours). Hover the slot for the usual usage card, or click ×; the same milestone does not repeat
• Drag anywhere; snap to left / right / top / bottom
• Two display styles: Ring usage (full rings + percent + dark dock) or Transparent icons (same rings and percents, no dock). The gear menu also has panel opacity and blur; on macOS the frost follows the D-shaped dock, a separate gear cabin, and rounded cards. Below 60% opacity, text and icons go dark
• Display value: Used quota (default) or Remaining quota. Rings, percents, and the detail card follow the choice; colors still follow remaining (red ≤ 20%, yellow ≤ 40%, green otherwise)
• On top / bottom edges, the percent sits to the right of each ring
• Click-through when the mouse is not on the bar
• A detached settings gear sits in its own circular cabin past the end of the bar (the dock shape is unchanged). Hover the gear to open settings; move away to close. Right-click the bar pins the same menu. × also closes it
• Automatic update checks are off by default. Opening the gear menu still checks once; a new version pops a separate notes window from the GitHub release (What’s new / 更新说明, matching the app language) beside the settings menu. × skips that version; hovering a slot hides the card. The gear menu still has the current version and Check for update; after a check, click the latest version or Install to download, install, and restart. If install fails, the GitHub download page opens
• App icon in the gear menu: Dock, menu bar, or neither (default). Menu-bar UB is quit-only. With neither, open settings from the gear, or reopen the app from Applications / the Start menu
• Auto-refresh every 60 seconds (configurable)
• Official brand icons; red when remaining ≤ 20% (used ≥ 80%), yellow when remaining ≤ 40% (used ≥ 60%), green otherwise

How usage and reset time are read

UsageBar does not estimate anything. It reuses credentials already on this computer and calls each vendor’s official usage endpoint.

Provider	Local credential	Official API	Ring / tooltip
Codex	~/.codex/auth.json	ChatGPT backend-api/wham/usage + wham/rate-limit-reset-credits	5-hour + weekly (+ monthly / extra windows if present); banked reset cards and expiry at the bottom of the card
Cursor	Cursor state.vscdb session (old cursorAuth/userId, or newer glass.lastSignedInAuthId / JWT sub)	cursor.com/api/usage-summary + Grok Bot weekly status	Monthly billing cycle: included + API (+ on-demand / team pool / Grok Bot weekly if present)
Grok	~/.grok/auth.json	cli-chat-proxy.grok.com/v1/billing + grok.com GetRemainingResets	Weekly and/or monthly (+ products / on-demand if present). Banked reset cards from the grok.com inventory (prepaid balance is not a reset card)
GLM	GLM_API_KEY / ~/.zai/config.json / cc-switch	api.z.ai or open.bigmodel.cn quota	All limits[] windows (5-hour, weekly, monthly, MCP, …). Reset cards come from a ZCode login session (zcode.z.ai coding-plan reset status), or an embedded list on the quota payload
ZCode	~/.zcode/v2/config.json Coding Plan key + credentials.json login	Same official quota API as GLM; reset cards from zcode.z.ai /api/v1/coding-plan/reset/status	All limits[] windows (5-hour, weekly, monthly, MCP, …). Banked 5-hour / weekly reset cards when ZCode is signed in
Claude	macOS Keychain Claude Code-credentials, or ~/.claude/.credentials.json	Anthropic api/oauth/usage	5-hour + weekly + scoped weekly (+ monthly extra usage if present)
Copilot	~/.config/github-copilot/apps.json / hosts.json, or gh hosts.yml, or GITHUB_TOKEN	GitHub copilot_internal/user	Monthly capped snapshots (usually Premium) + reset date
Gemini	~/.gemini/oauth_creds.json	Cloud Code Assist retrieveUserQuota	Per-model remaining fraction + reset
Antigravity	~/.gemini/antigravity-cli/antigravity-oauth-token	Cloud Code Assist fetchAvailableModels	Per-model remaining fraction + reset

Cursor session file:

• macOS: ~/Library/Application Support/Cursor/User/globalStorage/state.vscdb
• Windows: %APPDATA%\Cursor\User\globalStorage\state.vscdb
• Linux: ~/.config/Cursor/User/globalStorage/state.vscdb

Percent and reset timestamps come from the API (used_percent, autoPercentUsed, percentage, reset_at, billingCycleEnd, nextResetTime, …). Reset times are shown as a calendar date and 24-hour clock in the system timezone. Tokens that expire are refreshed locally when possible. A tool you are not signed into simply shows “no data”.

Install

Needs a working login on that same machine for whichever tools you show. The installer does not ship anyone’s account.

1. Download the latest build from Releases.

   • macOS Apple Silicon (M): aarch64.dmg
   • macOS Intel: x64.dmg
   • Windows: x64-setup.exe
   • Linux: .AppImage or .deb

2. macOS builds are ad-hoc signed (not Apple-notarized). After dragging UsageBar.app into Applications, run this once in Terminal (required on macOS Sequoia / Tahoe; “Right-click → Open” often does nothing):

   xattr -cr /Applications/UsageBar.app
   open /Applications/UsageBar.app

   The “UsageBar.app is damaged” dialog is Gatekeeper quarantine, not a broken download. Do not move it to the Trash.

3. Sign in to the tools you want to watch (Codex CLI, Cursor, Grok CLI, GLM, Claude Code, GitHub Copilot, Gemini CLI, Antigravity). UsageBar will pick up those sessions.

Build from source:

npm install
npm run tauri dev      # development
npm run tauri build    # local installer

Artifacts:

• macOS: src-tauri/target/release/bundle/dmg
• Windows: src-tauri/target/release/bundle/nsis
• Linux: src-tauri/target/release/bundle/appimage or deb

Push a v* tag to run GitHub Actions and publish macOS (Apple Silicon + Intel), Windows, and Linux (see .github/workflows/release.yml).

Menu

Hover the settings gear on the bar, or right-click the bar:

• Refresh now; auto-refresh 15s–10min or off
• Lock position / click-through (Don’t block clicks below)
• Snap left / right / top / bottom
• Display style: Ring usage / Transparent icons
• Display value: Used quota / Remaining quota
• Language: English (default) / 中文 — menus and usage cards follow it; vendor and model names stay in English
• Providers…: choose 1–10 providers and their order in the same gear popover. The bar shortens or lengthens to match; no empty — slots.
• Current version, Check for update, latest version (click to install), and auto-check (off by default). A new version pops a separate notes window beside the menu; open at login; quit
• App icon: Dock / menu bar / neither (default). Menu-bar UB only quits

All settings — edge, position, provider list and order, display style, display value, opacity, blur, app icon, language, refresh, lock, click-through, update prefs — are stored at ~/.usagebar/prefs.json and survive restarts and app updates.

FAQ

Why does one tool show “no data”?
That tool is not signed in on this computer, or UsageBar cannot read its local credential. Sign in with the official app / CLI first, then choose Refresh now.

Cursor says “Cursor login not found”.
UsageBar reads cursorAuth/accessToken from Cursor’s local state.vscdb (JWTs can be several hundred characters; older builds mistakenly dropped those). Then it tries the user id from cursorAuth/userId, or glass.lastSignedInAuthId / adminSettings.cachedAuthId / the access-token JWT sub. Open the Cursor desktop app on this machine and sign in. Installing UsageBar on another computer does not copy your Cursor session.

Grok shows “no data” but I am signed in.
Login is ~/.grok/auth.json. Newer Grok CLI unified-billing responses dropped creditUsagePercent; UsageBar now also reads /v1/billing monthly / on-demand fields, and still shows the weekly window when Apple-style percents are missing.

I sent UsageBar to a friend and they see no Cursor / Codex data.
Expected. Credentials stay on each machine. They need their own logins for the tools they show.

Claude / Copilot / Gemini / Antigravity shows “no data”.
Sign in with that tool’s official CLI or editor on this computer first. Claude reads Keychain / ~/.claude/.credentials.json. Copilot reads ~/.config/github-copilot. Gemini reads ~/.gemini/oauth_creds.json. Antigravity reads ~/.gemini/antigravity-cli/antigravity-oauth-token. UsageBar does not estimate tokens from local logs.

Does UsageBar upload chats or package my tokens?
No. It only reads local session files / env keys and calls official usage APIs. Tokens are never bundled into the installer.

I cannot click windows behind the bar.
Turn on Don’t block clicks below (on by default). When the pointer is not over the bar, clicks pass through.

I cannot click the bar or open the menu.
If click-through is on, click empty glass around the rings may pass through. Hover a ring or the gear. You can also turn click-through off, then lock the position.

macOS: “UsageBar.app is damaged and can’t be opened” / unidentified developer.
The file is not damaged. Chrome / Safari marks the download with a quarantine flag, and the release is not Apple-notarized. On Sequoia / Tahoe, right-click → Open and Privacy & Security usually do not help. Copy the app to /Applications, then:

xattr -cr /Applications/UsageBar.app
open /Applications/UsageBar.app

Ring colors?
Green: used < 60%. Yellow: 60%–80%. Red: ≥ 80%.

How do I set a GLM key?
Export GLM_API_KEY (or ZAI_API_KEY / Z_AI_API_KEY) in your shell, or use ~/.zai/config.json, or a GLM / 智谱 / z.ai provider in cc-switch.

ZCode vs GLM — same ring?
No. ZCode is 智谱’s coding agent; GLM is the model / API key. Providers → ZCode reads the Coding Plan key ZCode already saved. GLM reads your shell / .zai / cc-switch key. If those keys belong to the same Coding Plan, the percentages match; if they are different accounts, the rings differ. Reset cards need a signed-in ZCode session (~/.zcode/v2/credentials.json); UsageBar decrypts that local enc:v1: blob only to list cards, and never redeems them.

Windows / Linux notes.
Windows needs WebView2 (the installer can bootstrap it). The tray appears only if App icon is Menu bar; it is quit-only. Linux needs a working system tray for that option.

Privacy

• Credentials stay on your machine
• Requests go only to official vendor APIs
• No conversation content is uploaded
• No third-party telemetry

License

MIT