Usage – Real‑time quota monitor for Claude, Codex, Antigravity & Grok

What it does

usage is a desktop‑side utility that watches the token‑quota limits of several AI‑coding assistants (Claude Code, Codex, Google Antigravity, and the Grok CLI) and shows the remaining % in the macOS menu bar or Windows system‑tray. The indicator changes colour from green → yellow → red as the quota runs down, and clicking it opens a small panel with detailed breakdowns, outage alerts, and quick actions.

Who it’s for

• Developers who regularly use Claude Code, Codex, Antigravity or Grok in their daily coding workflow.
• Anyone who wants to avoid being surprised by a quota reset in the middle of a refactor.
• Teams that need a quick visual cue of remaining AI‑assistant budget without opening a browser or log file.

How it works (high‑level)

1. Data sources – The app reads local log files that Claude Code, Codex, Grok and Muse Code already write on your machine. For Antigravity it calls Google’s official quota endpoint using the OAuth token that the Antigravity CLI has stored.
2. Menu‑bar / tray UI – A tiny icon displays the current session/weekly quota percentage, colour‑coded. A click expands a panel showing per‑project token counts, cost estimates, and any outage banners.
3. Claude Code integration – An optional status‑line hook can be installed inside Claude Code. It adds a one‑line summary at the bottom of the Claude window and can enable extra helpers (side‑pane, token‑saver, beginner mode, etc.).
4. Reports & theming – The app can generate offline HTML/CSV reports of token trends and costs, and you can pick from 16 visual themes.
5. CLI mode – For Linux or head‑less use, uvx usage-cli (or uv tool install usage-cli) runs a terminal UI and provides a usage status --json command that other tools (Starship, tmux, custom scripts) can consume.

Main features

Feature	What you see / do	Why it matters
Quota monitor	Green‑yellow‑red icon with percentage; click for session, weekly, and per‑project breakdowns.	Immediate visual feedback, prevents surprise quota exhaustion.
Antigravity & Grok cards	Shows Gemini pool usage or Grok weekly credit alongside Claude/Codex.	Keeps all your AI‑coding budgets in one place.
Outage alerts	Red banner when Claude, Claude API or Codex API status pages report problems.	Lets you pause work instead of waiting for a failed request.
Context & cache warnings	Status line nudges you to /clear or /compact when the context window is filling.	Saves tokens that would otherwise be wasted on large prompts.
Claude Code side‑pane	Quotas, other conversations, and background jobs displayed next to the editor.	Reduces context switches; you can monitor multiple chats at once.
Progress Concierge	When you start a new session, the AI is reminded of the last request, uncommitted changes and open TODOs.	No need to manually recap; saves time and tokens.
Token‑Saver	Asks Claude/Codex for shorter, plainer replies while keeping code exact.	Cuts average reply length by ~40 % (as measured by the author).
Beginner & Quota‑Aware modes	Optional explanations of technical terms and warnings when a task would exceed remaining quota.	Helpful for newcomers and for budget‑conscious work.
HTML reports	Daily/weekly token trends, cost, project rankings, “Year in Review” heatmap; export to HTML, CSV, PNG.	Offline analysis of AI usage and budgeting.
16 visual themes	Classic, Matrix, Windows‑95, Newspaper, etc.	Personalise the look to match your desktop style.
Cross‑platform	macOS (menu bar)	Windows (system‑tray)

Installation & getting started

• macOS – brew install --cask aqua5230/usage/usage (recommended) or download the .app zip from the latest release.
• Windows – Download usage-windows.zip, unzip, run usage.exe. Requires Edge WebView2 (bundled on most Windows 10/11 machines).
• Linux / any OS (terminal only) – uvx usage-cli (no permanent install) or uv tool install usage-cli for a persistent usage command.
• After the first launch, click Set Up Status Line in the pop‑over to install the Claude Code hook (or run the equivalent command from source). Restart Claude Code/Codex afterwards.

Limitations & considerations

• The app only reads local logs; if you clear those logs you lose the historical data.
• Antigravity quota requires network access and the stored OAuth credential; otherwise the card is hidden.
• Beginner‑mode and Quota‑Aware mode send a single Claude request to fetch term explanations – a tiny extra quota cost.
• On Linux the UI is limited to the terminal version; the full menu‑bar/ tray UI is macOS/Windows‑only.
• All cost estimates use built‑in model‑pricing tables and are calculated offline.

Quick‑start checklist

1. Install the app for your platform.
2. Run a Claude Code, Codex, Antigravity or Grok session at least once so logs are created.
3. Open the menu‑bar/tray icon and click Set Up Status Line to enable the Claude integration.
4. Choose a visual theme you like.
5. (Optional) Turn on Beginner Mode or Quota‑Aware Mode from the settings panel.
6. Use usage status --json in your shell or tmux config if you want the numbers elsewhere.

---

All details above are taken directly from the project's README; no additional features have been inferred.