<p align="center"> <img src="docs/readme-logo.png" alt="usage logo" width="128"> </p>

usage

Your Claude Code, Codex, Antigravity and Grok CLI quota, always on screen.

usage puts your 5-hour and weekly limits in the macOS menu bar or Windows system tray, colored from green to red. Hitting the limit halfway through a long refactor is a bad way to find out you were running low. Now you see it coming. There's nothing to run and no page to open.

繁體中文 · 简体中文 · English · 日本語 · 한국어  |  Discussions  |  Landing page

<p align="center"> <img src="docs/showcase-v3.en.png" alt="usage — Claude Code, Codex, and Antigravity quota pinned to the macOS menu bar" width="820"> </p>

Claude Code and Codex numbers come from log files already on your machine. Antigravity quota comes from Google's official quota endpoint, using the sign-in the Antigravity CLI already stores locally.

usage also helps you spend less. The status line warns you before your context window bloats or your prompt cache goes cold, and a Token Saver toggle keeps replies short. In an A/B test on real sessions, late replies stayed ~40% shorter instead of growing 84% longer.

Quick Start

brew install --cask aqua5230/usage/usage

It lands in your Applications folder automatically. Open it once; if macOS 15 or later blocks it, go to System Settings → Privacy & Security, scroll down, and click Open Anyway. On macOS 14 or earlier, 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.

Not on macOS? uvx usage-cli runs the terminal interface anywhere, Linux included — no install, no menu bar.

Jump to: What You Get · Privacy · Requirements · Install · Status Line · Claude Code Side Pane · Windows · Themes · Troubleshooting · Comparison · Not a Fit? · Development

What You Get

Live Visibility

• 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. Antigravity keeps two separate quota pools: the card shows Gemini by default, and tapping the Gemini ⇄ tag next to the title switches it to Claude / GPT — the choice is remembered.
• Grok CLI Support: A fourth card reads Grok CLI's weekly credit percentage straight from its own local debug log. Grok CLI doesn't expose session or burn-rate data, so the card shows a single weekly bar; its per-request token usage still counts toward today's cost and project totals like Claude Code and Codex.
• Muse Code Spending: Muse Code's per-request tokens and cost count toward today's cost, project totals, the HTML report, and the usage CLI, read from its own local session logs. Muse keeps no local quota data, so there is no Muse quota card.
• 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. Antigravity isn't covered; it has no public status page.
• Context Nudges & Notifications: When your context window hits 70% — or earlier when it is filling fast — the status line nudges you to /clear or /compact to prevent token waste. You can also opt-in to system notifications for quota limits and recoveries.
• Prompt Cache Health: The status line shows Claude Code's prompt cache hit rate. For 10 minutes after the cache misses, it also says why — the model changed, the tools changed, you sat idle past the 5-minute TTL, and so on — so you can tell whether the extra tokens came from something you did. The hit rate needs Claude Code 2.1.251 or newer and the reason needs 2.1.260 or newer; on older versions those parts simply don't appear.
• Hide Sections: Only use one or two of the tools? Hide the Claude Code, Codex, Grok CLI, or Antigravity section from the menu bar and panels completely with a single click.

Workflow Helpers

• Progress Concierge: Open a new Claude Code session and usage hands your last progress straight to the AI, including your last request, uncommitted changes, and unfinished todos. No /resume, no recap. When you do /resume a conversation that sat long enough for its cache to expire, it warns you how many tokens the next message will re-send and suggests /compact first. Off by default.
• Token Saver: A menu-bar toggle asks Claude Code and Codex to answer more tersely and in plainer language, 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.
• Claude Code side pane (macOS and Windows): Quotas, conversations, and background jobs inside Claude Code. See the side pane.
• Auto-start 5-hour Session: Off by default. Turn it on and, right after a 5-hour quota resets, usage sends one tiny message to each tool (Claude with Haiku, Antigravity with Gemini 3.5 Flash Low, Codex with its cheapest model) so the next 5-hour window starts counting right away. Those messages do use a little quota, but the amount is negligible. Checking your quota never sends a message; only this switch does.
• Terminal Integration: usage status --json hands your Claude Code, Codex, Antigravity, and Grok quota to any tool that can run a command — Starship, tmux, or your own scripts. Reads the same local files as the menu bar. Ready-made snippets.
• 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.

Stay Current

• 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.

Reporting & Insight

• 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.

Experience & Customization

• 16 Visual Themes: Switch between panel styles including Default, Matrix, Windows 95, Vintage Newspaper, Cloud Observation, Midnight Aquarium, Prism Arcade, Black Hole, World Cup 2026, Lepidoptera, Migration, Stained Glass, Origami, Sketchbook, Heart Monitor, and Catppuccin (official palette, all four flavors).
• Place the Panel Anywhere: Drag the panel 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.
• Automatic Localization: UI text is available in Traditional Chinese, Simplified Chinese, English, Japanese, and Korean, automatically matching your system settings.

Privacy & Data Sources

• Claude Code and Codex numbers are read from local log files on your machine.
• 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. usage reads that credential without writing it back and keeps any refreshed access token in memory only; the call itself reads quota metadata.
• 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.

Requirements

• macOS 12 (Monterey) or newer, or Windows 10/11
• Claude Code, Codex, Antigravity, or Grok CLI has been used at least once (so local usage data exists).
• (Source runs only) Python 3.13.

Install

1. Homebrew (Recommended)

Installing via Homebrew means a single brew upgrade --cask usage keeps it current.

brew install --cask aqua5230/usage/usage

(First launch: on macOS 15 or later, open System Settings → Privacy & Security, scroll down, and click Open Anyway. On macOS 14 or earlier, right-click usage.app in Finder → Open to pass Gatekeeper.)

2. Download for macOS

1. Download the latest usage.app.zip from the GitHub Releases page.
2. Unzip it and drag usage.app into your Applications folder.
3. First launch: on macOS 15 or later, open System Settings → Privacy & Security, scroll down, and click Open Anyway. On macOS 14 or earlier, in Finder, right-click usage.app → Open → confirm Open.

3. uvx (zero install, any OS)

Run uvx usage-cli to open the terminal interface directly. uv automatically prepares Python 3.13, so no separate Python installation is needed.

For a persistent command, run uv tool install usage-cli, then use usage (for example, usage status --json). This installation path provides the CLI only, not the menu bar app.

On Linux, usage setup installs the Claude Code status line as well, so quota shows up under your prompt the same way it does on macOS and Windows. CI verifies this on Ubuntu. The menu bar and system tray apps remain macOS- and Windows-only.

First Launch: Set Up the Status Line

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 (on macOS, fully Cmd+Q Claude Code and re-open it; on Windows, restart your terminal or start a new session).

The same button also sets up a status line for the Antigravity CLI and for Grok CLI when they are installed on your machine, and does nothing at all when they aren't. Any status line you configured there yourself is backed up first and restored when you turn the switch off.

Once set up, the bottom of the Claude Code window will show a status line like this:

<p align="center"> <img src="docs/statusline.en.gif" alt="Claude Code statusLine display (English)" width="900"> </p>

Claude Code Side Pane

See your quota, other conversations, and background jobs without leaving Claude Code. Available on macOS and Windows.

<p align="center"><img src="docs/side-pane.png" alt="Claude Code side pane showing quotas, conversations, and background jobs" width="637"></p>

What you’ll see

• Quotas: Your 5-hour and weekly limits.
• Claude conversations: Conversations waiting for your permission or MCP input are marked in yellow.
• Background jobs: Includes subagents started by Claude with the Agent tool and their status.

How to enable

1. In the usage menu bar menu (macOS) or the system-tray panel menu (Windows), check Claude Code side pane.
2. Open a new conversation or run /reload-plugins.
3. At terminal widths ≥144 columns, the pane opens on the right automatically. In narrower terminals, enter /usage-dash.

<details> <summary>Compatibility and updates</summary>

• Requires a recent Claude Code with mod support; tested with 2.1.289.
• The pane docks on the right only in Claude Code's fullscreen layout; otherwise it appears above the prompt. On Windows, enabling the pane turns the fullscreen layout on as well, and turning the pane off switches it back.
• The built-in macOS Terminal supports only 256 colors and may show a gray background. Select an ANSI dark theme in /config.
• When the usage app starts, it automatically updates an enabled pane to the bundled version.

</details>

Windows Support

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. If SmartScreen shows Windows protected your PC on first launch, click More info → Run anyway. The tray UI requires Microsoft Edge WebView2 Runtime, which is normally included with Windows 10 and 11.

The system-tray icon shows the remaining session quota percentage for Claude or Codex. Choose Tray Display Source → Claude Code / Codex in the right-click menu or panel menu; the change applies immediately and survives restarts (default: Claude). If Codex has no session window, the icon uses its weekly quota instead and the tooltip identifies that window. Missing quota data shows --. The tooltip summarizes both tools, with the selected source first. Left-click opens the same 16 quota themes available on macOS (Default plus the other fifteen) in WebView2. Right-click also provides Reset Panel Position and Quit; panel switching, refresh, launch at login, and update checks are in the panel menu.

Enable Show Taskbar Quota in either menu for a transparent Codex: 92% label inside the taskbar, immediately left of the notification area. It follows taskbar position, scaling, and light/dark theme, and hides during fullscreen use or taskbar auto-hide. Click the label to open the panel. If buttons leave insufficient space, it moves just outside the taskbar. The normal app icon remains as a menu entry point; the label follows the selected source and quota window.

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.

Code signing policy

Free code signing provided by SignPath.io, certificate by SignPath Foundation.

Team roles:

• Committers and reviewers: aqua5230
• Approvers: aqua5230

Privacy policy: this program will not transfer any information to other networked systems unless specifically requested by the user or the person installing or operating it. See Privacy & Data Sources for the network calls usage makes on your behalf and how to avoid them.

Theme Gallery

Switch between 16 visual themes directly from the UI:

<p align="center"> <img src="docs/classic.en.png" width="24%" alt="Classic theme" /> <img src="docs/matrix.en.png" width="24%" alt="Matrix theme" /> <img src="docs/win95.en.png" width="24%" alt="Windows 95 theme" /> <img src="docs/newspaper.en.png" width="24%" alt="Newspaper theme" /> <img src="docs/cloud_observation.en.png" width="24%" alt="Cloud Observation theme" /> <img src="docs/aquarium.en.png" width="24%" alt="Midnight Aquarium theme" /> <img src="docs/prism_arcade.en.png" width="24%" alt="Prism Arcade theme" /> <img src="docs/stained_glass.en.png" width="24%" alt="Stained Glass theme" /> <img src="docs/origami.en.png" width="24%" alt="Origami theme" /> <img src="docs/black_hole.en.png" width="24%" alt="Black Hole theme" /> <img src="docs/world_cup.en.png" width="24%" alt="World Cup 2026 theme" /> <img src="docs/lepidoptera.en.png" width="24%" alt="Lepidoptera theme" /> <img src="docs/migration.en.png" width="24%" alt="Migration theme" /> <img src="docs/catppuccin.en.png" width="24%" alt="Catppuccin theme" /> <img src="docs/sketchbook.en.png" width="24%" alt="Sketchbook theme" /> <img src="docs/heart_monitor.en.png" width="24%" alt="Heart Monitor theme" /> </p>

Troubleshooting

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 | macOS 15 or later: System Settings → Privacy & Security → scroll down → Open Anyway. macOS 14 or earlier: right-click usage.app in Finder → Open | | Windows shows "Windows protected your PC" | SmartScreen doesn't recognize the download yet | Click More info → Run anyway |

Comparison

| Feature | usage | ccusage | TokenTracker | |---------|:-----:|:-------:|:------------:| | Always on screen | ✅ | — | ✅ | | macOS menu bar & Windows system tray | ✅ | — | macOS only | | Claude Code & Codex usage | ✅ | Claude only | ✅ | | Antigravity usage (Gemini and Claude / GPT) | ✅ | — | — | | Grok CLI usage | ✅ | — | — | | Muse Code token spend | ✅ | — | — | | Claude Code & Codex service-status alerts | ✅ | — | — | | HTML deep reports & UI | ✅ | ✅ | — | | AI Update Daily | ✅ | — | — | | Progress Concierge & Token Saver | ✅ | — | — | | Token-waste Health Check | ✅ | — | — | | Open-source license | AGPL-3.0 | MIT | — |

When usage Isn't the Right Fit

• 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, Antigravity, or Grok CLI — there's no local usage data for usage to read.
• You want a menu bar on Linux. Only macOS and Windows have one today, though the terminal interface (uvx usage-cli) runs on Linux.

Development

Building from source, configuring custom agents, or running the terminal TUI? See the development docs.

License

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