Quota visibility for Claude Code, Codex, and Antigravity, built into the macOS menu bar and Windows system tray.
Running out of quota mid-session is expensive — especially during a long refactor or debugging run that depends on Claude Code. usage surfaces 5-hour and weekly limits before you hit the wall, and keeps them visible the whole time. There's no command to run and no page to open; the answer is just there, where you already look.
繁體中文 · 简体中文 · English · 日本語 · 한국어 | Discussions | Landing page
Claude Code and Codex numbers are read passively from log files already on your machine, so watching your quota never calls Anthropic or OpenAI's LLM APIs and never costs you a token. Antigravity is the one exception: its quota comes from Google's official quota endpoint using the sign-in the Antigravity CLI already stores locally — a metadata call that doesn't consume your model quota either.
brew install --cask aqua5230/usage/usageIt lands in your Applications folder automatically. Right-click Open once to pass Gatekeeper, then click the menu bar icon. Prefer a direct download or want the full setup flow? See Install below.
Jump to: What You Get · Privacy · Requirements · Install · Windows · Themes · Troubleshooting · Comparison · Not a Fit? · Development
- Always-on Monitor: Your quota lives in the menu bar, color-coded from green to red. Click when you want the full session, weekly, and per-project breakdown.
- Antigravity Support: Antigravity (Gemini) session and weekly quota show up as a third card in every theme except World Cup 2026, which stays a two-team HUD. Numbers come straight from the official quota API, using the sign-in the Antigravity CLI already keeps on your machine — refreshed every few minutes, with live reset countdowns.
- Service Status Alerts: An orange-red banner appears when Claude Code, Claude API, or Codex API has an outage or degraded performance, read from their public Statuspage.io pages — never an LLM usage API. Antigravity isn't covered; it has no public status page.
- Context Nudges & Notifications: When your context window hits 70%, the status line nudges you to
/clearor/compactto prevent token waste. You can also opt-in to system notifications for quota limits and recoveries. - Hide Sections: Only use one or two of the tools? Hide the Claude Code, Codex, or Antigravity section from the menu bar and panels completely with a single click.
- Progress Concierge: Open a new Claude Code session and
usagehands your last progress straight to the AI, including your last request, uncommitted changes, and unfinished todos. No/resume, no recap. Fully local, off by default. - Token Saver: A menu-bar toggle asks Claude Code and Codex to answer more tersely, saving output tokens while keeping code and error messages byte-exact. A light reminder keeps long conversations from drifting back to verbose — in an A/B test on real sessions, late replies stayed ~40% shorter instead of drifting 84% longer.
- Token-waste Health Check: A daily background diagnosis scans your logs for waste, including repeated file reads, polluter directories, and noisy Bash output. If it finds issues, a one-line heads-up appears; say "show me" and the AI walks you through fixes.
- AI Talent Market: Bring a ready-made AI team into Claude Code. Browse and install curated subagent personas into
~/.claude/agents/instantly. Runs fully locally via the bundled CLI. - AI Council: Open a dedicated window and run a multi-round discussion between Claude Code, Codex, and Antigravity — pick participants, models, and a debate style, with a token estimate up front. Steer it between rounds, see who dissents in the consensus tally, and let it stop early once everyone agrees. Seats can wear AI Talent Market personas and reference real files via an optional read-only folder.
- AI Update Daily: Opens a daily-updated public page covering Claude Code, Codex, and Antigravity, with the full history kept. Reviewed items get a plain-language summary in all five UI languages; unreviewed ones show the original source text.
- Deep HTML Reports: Shareable HTML reports of daily and weekly token trends, project rankings, and cost — including a Year in Review with a contribution heatmap and "Wrapped" summary. A "What you worked on" section lists the names Claude Code gave your recent conversations, so the numbers arrive with context. Export as .html, .csv, or .png, fully offline, with optional project-name masking that covers those titles too.
- 13 Visual Themes: Switch between panel styles including Classic, Matrix, Windows 95, Newspaper, Cloud Observation, Midnight Aquarium, Prism Arcade, Black Hole, World Cup 2026, Lepidoptera (blueprint), Stained Glass, Origami, and Catppuccin (official palette, all four flavors).
- Place the Panel Anywhere: The panel is no longer pinned under the menu bar icon. Drag it from any empty spot to wherever you want it, and it reopens there next time. It stays put when another app takes focus — a second click on the menu bar icon, or Escape, closes it.
- Drag to Reorder: Grab any quota card and drag it up or down to swap the order — the arrangement is shared across every theme with quota cards (all except World Cup 2026) and survives restarts.
- Spirit Companions: A small animated white silhouette lives beside your usage percentages — a phoenix for Claude, a dragon for Codex, a lion for Antigravity. Each accelerates dynamically as its own tool's token burn rate climbs.
- Automatic Localization: UI text is available in Traditional Chinese, Simplified Chinese, English, Japanese, and Korean, automatically matching your system settings.
- Claude Code and Codex numbers are read only from local log files on your machine; reading them never calls Anthropic or OpenAI's LLM APIs.
- Antigravity quota requires network access, and only if you use it: quota is fetched from Google's official quota endpoint using the OAuth credential the Antigravity CLI already stored after sign-in — read from macOS Keychain, Windows Credential Manager, or a local token file depending on CLI version.
usagereads that credential without writing it back and keeps any refreshed access token in memory only; the call itself only reads quota metadata and never consumes your model quota. - Background network activity: the Antigravity quota/token endpoints above, public Claude and Codex status pages to flag outages, a public model-pricing table to estimate cost (falls back to built-in prices offline), and occasionally checking GitHub for a new version. Claude Code and Codex log contents are never uploaded.
- macOS 12 (Monterey) or newer, or Windows 10/11
- Claude Code, Codex, or Antigravity has been used at least once (so local usage data exists).
- (Source runs only) Python 3.13.
Installing via Homebrew means a single brew upgrade --cask usage keeps it current.
brew install --cask aqua5230/usage/usage(First launch: right-click usage.app in Finder → Open to pass Gatekeeper).
- Download the latest
usage.app.zipfrom the GitHub Releases page. - Unzip it and drag
usage.appinto your Applications folder. - First launch: in Finder, right-click
usage.app→ Open → confirm Open.
Windows has the full core experience: the system-tray UI, Claude Code status-line hook, and Codex history parsing all work natively. Download usage-windows.zip from the latest GitHub Release, unzip it, then run usage.exe—no installer is needed. The tray UI requires Microsoft Edge WebView2 Runtime, which is normally included with Windows 10 and 11.
The system-tray icon updates with your Claude quota percentage; its tooltip summarizes the Claude and Codex windows. Left-click opens the same 13 quota themes available on macOS (Classic plus the other twelve) in WebView2. Right-click provides panel switching, refresh, launch at login, check for updates, and quit.
Windows differences: the panel opens at the bottom-right of the working area rather than next to the tray icon; update prompts use a system Yes/No dialog; and the AI Talent Market and AI Council panels are macOS-only.
If you've used Codex, usage picks up its history automatically. For Claude Code, click the "Set Up Status Line" button in the app popover to install the sync hook.
Restart the relevant tool afterward (fully Cmd+Q Claude Code and re-open it).
Once set up, the bottom of the Claude Code window will show a status line like this:
Switch between 13 visual themes directly from the UI:
If the menu bar shows --, it's usually not broken — there's just no local data yet.
| Symptom | Likely cause | Fix |
|---|---|---|
Menu bar shows -- |
No data yet, or Claude Code hook not refreshed | Run one Codex conversation. For Claude Code, click "Set Up Status Line" (from source: python3 main.py --setup) |
ImportError from main.py inside usage.app |
The bundled main.py needs the bundle's own interpreter and cannot be run by hand |
Don't run that copy. Click "Set Up Status Line" in the app, or clone the repo to run from source |
| Accidentally hit "Quit" | Process terminated | Relaunch usage.app from Spotlight or Applications. (launchctl start com.lollapalooza.usage only works if you enabled Launch at Login.) |
| Status says "N minutes stale" | Claude Code isn't running | Open Claude Code and let it run |
| Codex section is empty | No Codex history found | Run a Codex conversation to generate logs |
| Today's cost shows $0.00 | Model pricing missing | Delete ~/.usage/pricing_cache.json or check USAGE_DEBUG=1 |
| Antigravity card is missing | Antigravity CLI not installed or not signed in | Install and sign in to the Antigravity CLI; the card appears automatically once a background quota fetch succeeds |
| App won't open | macOS Gatekeeper blocked it | Right-click usage.app in Finder → Open |
| Feature | usage | ccusage | TokenTracker |
|---|---|---|---|
| Always on screen | ✅ | — | ✅ |
| macOS menu bar | ✅ | — | ✅ |
| Claude Code & Codex usage | ✅ | Claude only | ✅ |
| Antigravity (Gemini) usage | ✅ | — | — |
| Claude Code & Codex service-status alerts | ✅ | — | — |
| HTML deep reports & UI | ✅ | ✅ | — |
| AI Talent Market | macOS only | — | — |
| AI Council | macOS only | — | — |
| AI Update Daily | ✅ | — | — |
| Progress Concierge & Token Saver | ✅ | — | — |
| Token-waste Health Check | ✅ | — | — |
| No LLM API calls to read quota | ✅ | ✅ | ✅ |
| Open-source license | AGPL-3.0 | MIT | — |
- You only live in the terminal and don't want another menu bar icon running in the background — a one-off CLI check fits better.
- You don't use Claude Code, Codex, or Antigravity — there's no local usage data for
usageto read. - You're on Linux — only macOS and Windows are supported today.
Building from source, configuring custom agents, or running the terminal TUI? See the development docs.
Licensed under AGPL-3.0-only (see LICENSE). If you fork or redistribute a modified version, please credit the original author and link back to: https://github.com/aqua5230/usage