Quota visibility for Claude Code, Codex, and Antigravity, built into the macOS menu bar and Windows system tray.
Keep Claude Code, Codex, and Antigravity quota in view while you work. usage puts session limits, weekly limits, and cost context in the macOS menu bar or Windows system tray, so you can manage usage before it interrupts a session.
繁體中文 · 简体中文 · English · 日本語 · 한국어 | Discussions | Landing page
usage keeps your Claude Code, Codex, and Antigravity quota pinned to the top-right of your screen, color-coded so warning levels read at a glance. Every number is read passively from local files already on your machine. It never calls the Anthropic / OpenAI API and never reads the Keychain, so the monitor itself never adds to your token usage.
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.
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.
- 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 panel. 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.
- 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 for the session, saving output tokens while keeping code and error messages byte-exact. A light per-message reminder keeps replies from drifting back to verbose in long conversations (A/B-tested: late-conversation replies stay ~40% shorter).
- 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.
- Deep HTML Reports: Instant, shareable HTML deep reports showing daily and weekly token trends, project rankings, and cost. Includes a Year in Review featuring a contribution heatmap and "Wrapped" summary. One click saves a copy as .html, .csv, or a .png image — fully offline, with optional project-name masking.
- TUI & CLI: Prefer the terminal? Run the rich TUI dashboard with
python3 main.py --tui, or generate deep analytics withpython3 usage_cli.py report.
- 10 Visual Themes: Switch between panel styles including Classic, Matrix, Windows 95, Newspaper, Cloud Observation, Midnight Aquarium, Prism Arcade, Black Hole, World Cup 2026, and Lepidoptera (blueprint).
- Drag to Reorder: Grab any quota card and drag it up or down to swap the order — the arrangement is shared across every theme and survives restarts.
- 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 Update Daily: Clicking this menu item opens the public web page in your default browser. The page auto-updates every day, covers Claude Code, Codex, and Antigravity, and keeps the full history; reviewed updates show a plain-language summary in all five languages, while unreviewed ones show the official source text.
- 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.
- Usage numbers are read only from local log files on your machine.
- It never calls the Anthropic / OpenAI API and never reads the Keychain (macOS's password vault).
- Antigravity quota is fetched from the official quota API using the OAuth token the Antigravity CLI stores locally after sign-in.
usagetreats that token file as strictly read-only, and the call itself only reads quota metadata — it never consumes your model quota. - The only network activity: fetching a public model-pricing table to estimate cost (falls back to built-in prices offline) and occasionally checking GitHub for a new version. Nothing is ever uploaded.
- macOS 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 TUI, 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 11 HTML panels as macOS (Classic plus the ten themes) 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 panel is 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 10 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" or run python3 main.py --setup |
| Accidentally hit "Quit" | Process terminated | Launch usage.app from Spotlight / Applications, or run launchctl start com.lollapalooza.usage |
| 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 |
| App crashes immediately (arm64) | py2app bundling bug in older versions | Upgrade to v0.11.1 or newer |
| Feature | usage | ccusage | TokenTracker |
|---|---|---|---|
| Always on screen | ✅ | — | ✅ |
| macOS menu bar | ✅ | — | ✅ |
| Claude Code & Codex usage | ✅ | Claude only | ✅ |
| Antigravity (Gemini) usage | ✅ | — | — |
| HTML deep reports & UI | ✅ | ✅ | — |
| AI Talent Market | ✅ | — | — |
| AI Update Daily | ✅ | — | — |
| Progress Concierge & Token Saver | ✅ | — | — |
| Token-waste Health Check | ✅ | — | — |
| Zero API calls | ✅ | ✅ | ✅ |
| Open-source license | AGPL-3.0 | MIT | — |
Want to run the terminal TUI, configure custom agents, or build the app yourself? Check out 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