# Four tools are tracked and the World Cup theme has room for two cards

> A Python menu bar and system tray utility that reads Claude Code, Codex, Grok CLI and Muse Code logs to show five-hour and weekly limits, with Antigravity read from a Google quota endpoint. AGPL-3.0-only, Python 3.13 and newer, released as the usage-cli distribution.

**aqua5230/usage** — macOS menu bar & Windows tray app pinning Claude Code, Codex & Antigravity quota, burn rate, and cost to your screen. Local-first, no LLM API calls. HTML reports, 10 themes.

- Repository: https://github.com/aqua5230/usage
- Website: https://aqua5230.github.io/usage/
- Stars: 331 · Forks: 59
- Language: Python
- License: AGPL-3.0
- Published: 2026-09-15 · Updated: 2026-09-15 · Language: en
- Canonical page: https://hysenlabs.com/projects/aqua5230-usage

## The World Cup 2026 theme has room for two cards, the others have four

Four tools are tracked, and each is presented differently. Antigravity appears as a third card in every theme except World Cup 2026, which stays a two-team HUD. That single exception is the only place the display shrinks, and it shrinks silently: no note in the file explains that choosing the football theme costs you a data source. Antigravity also keeps two separate quota pools, so the card shows Gemini by default and tapping a small tag beside the title switches it to Claude or GPT, with the choice remembered. Grok CLI gets a fourth card, but only a weekly credit percentage, because it does not expose session or burn-rate data; its per-request tokens still count toward today's cost. Muse Code has no card at all, since it keeps no local quota data, but its tokens and cost feed today's total, project totals, the HTML report and the terminal interface.

## No model API calls, and three outbound paths that are not model calls

The headline privacy claim is precise rather than absolute. Claude Code and Codex numbers come from log files already on the machine, so watching quota never calls Anthropic's or OpenAI's APIs and never costs a token. Antigravity is named as the one exception: its quota comes from Google's official quota endpoint, using the sign-in the Antigravity CLI already stores locally, which the file classes as a metadata call. Two more outbound paths exist further down and are not counted against model quota either. The service status banner reads the public Statuspage.io pages for Claude Code, the Claude API and the Codex API, with Antigravity excluded because it has no public status page. And AI Update Daily opens a daily-updated public page covering Claude Code, Codex and Antigravity, keeping full history. So the traffic is metadata and status, not inference, but it is not zero.

## The cache segment disappears entirely below Claude Code 2.1.251

Prompt cache health is the feature that depends most tightly on an external tool's version, and it degrades by vanishing rather than by warning. The status line shows Claude Code's prompt cache hit rate with a countdown to expiry, so you can tell whether finishing now reuses the cached context or lets it go cold and re-sends everything. Once the cache has gone cold, the countdown changes into how many tokens your next message will re-cache, which is the number you actually want. The condition attached to it is a version floor: Claude Code 2.1.251 or newer, and on older versions the segment simply does not appear. Nothing tells you why it is missing. A user on an older client sees a shorter status line and has no way to tell an absent feature from a quiet cache, which is the opposite of what a warning light is for.

## Progress Concierge puts uncommitted changes into a prompt

This is the helper with the widest blast radius, and the file marks it as off by default. Open a new Claude Code session and usage hands your last progress straight to the AI: your last request, uncommitted changes, and unfinished todos, so you skip the /resume and the recap. It also handles the other direction of the cache problem: when you do run /resume on a conversation that sat long enough for its cache to expire, it warns how many tokens the next message will re-send and suggests /compact first. Both halves are described as fully local. The first half is still the one to think about, because uncommitted work is the state most apt to be experimental, half-finished and not meant for a model, and the feature sends it without asking per session. Whether the toggle is per project or global is not stated anywhere in the visible documentation.

## The uv lock names three platforms because a Windows re-lock once broke macOS

The packaging configuration carries a maintenance note that is worth more than most changelog entries. Under the uv section, environments is declared for darwin, win32 and linux, and the comment above it explains why: without that list, uv resolves against the running interpreter's environment and rewrites the platform markers it can prove false there, so a re-lock performed on Windows turns every darwin dependency into an impossible python version constraint, silently drops PyObjC from the lock, and breaks the macOS build. In other words the three-entry list is not a nicety, it is a guard against a lock file that looks fine and produces an install with no Cocoa bindings. A contributor who re-locks without the guard would not see an error at lock time, only a broken application on the other platform, which is the worst shape for a build trap to take.

## Four PyObjC frameworks load on every macOS install, and one dependency has a ceiling

```bash
brew install --cask aqua5230/usage/usage
```

That one command puts the application in your Applications folder automatically, and the rest of the path splits by macOS version: on 15 or later the application is blocked and the route is System Settings, Privacy and Security, down to an Open Anyway button, while on 14 or earlier there is no Settings panel involved and you right-click Open once. Two procedures decided by the operating system rather than by anything the user does. Underneath, the dependency list is short and platform-shaped. On macOS the package requires four PyObjC frameworks at 11.0 or newer: Cocoa for the menu bar, Quartz, UserNotifications for the opt-in alerts, and WebKit for the HTML reports. On Windows the extras are four different libraries, pystray for the tray icon, pillow for the icon itself, pywebview for the window, and windows-toasts for notifications. Exactly one entry carries an upper bound, rich pinned to 15.0.0 or newer and below 16.0.0, while every other dependency is open ended at a floor. Python 3.13 or newer is required, the distribution is named usage-cli while the repository is called usage, and two console scripts are registered, usage and usage-cli, both pointing at the same main function.

## Forty percent shorter instead of 84 percent longer, with no sample attached

Token Saver is a menu bar toggle that asks Claude Code and Codex to answer more tersely and in plainer language, and the file is specific about the mechanism: it saves output tokens while keeping code and error messages byte-exact, and a light reminder nudges long conversations back toward terseness. The supporting number appears twice, in the opening and again in the feature list: in an A/B test on real sessions, late replies stayed about 40% shorter instead of growing 84% longer. That sentence carries no session count, no duration, no model version and no statement of which side of the test was which. The mechanism is prompt-level rather than a model setting, which means the effect depends on how well a given model follows an instruction to be brief, and the byte-exactness claim for code and error messages is the part that has to hold for the saving to be worth anything.

## Eight badges with one duplicate, and sixteen modules at the root

The badge row holds eight links and every one is written without a label. Two of the eight point at the same latest-releases page, so one is a duplicate in the source rather than a rendering artefact. The rest name the stargazers list, a workflow file called check.yml, the PyPI project for usage-cli, the Python site, the licence and a bestpractices.dev project page, which is a third-party directory rather than anything in the repository. The root layout is unusually flat for a project this size. Sixteen Python modules sit at the top level, among them doctor.py, prefs.py, pricing.py, project_resolver.py, service_status.py and setup_app.py, plus eight files whose names start with usage_, four of which are separate statusline entry points for the base case, Antigravity, Grok and a forwarder. Alongside them sit fourteen directories including adapters, loaders, analyzer, quota, menubar, panels, wintray, tui and ui, a fuzz directory paired with a ClusterFuzzLite configuration, a Claude Code plugin directory, and a file that tells git to hide blame for rewritten commits.

## Conclusion

usage is worth installing if you burn through a five-hour window mid-refactor and want the bar before you hit it, since it reads the same log files the tools already write and exposes the same numbers to Starship or tmux through a JSON command. It is not the right tool if you treat the badge as a private matter, because three outbound paths exist: a Google quota endpoint for Antigravity, three public status pages, and a daily updates page. It is also not usable on an older Claude Code for the cache feature, and the World Cup 2026 theme silently drops a card. Before you install, decide whether you want the Antigravity quota check enabled, read what Progress Concierge injects since it includes uncommitted changes, and check that your Claude Code version clears 2.1.251 if the cache countdown is the reason you want it.

## FAQ

### Does aqua5230/usage call Anthropic or OpenAI to show my quota?

No. Claude Code and Codex numbers come from log files already on your machine, so watching quota never calls those APIs and never costs a token. Antigravity is the stated exception, read from Google's official quota endpoint using the sign-in the Antigravity CLI already stores, and the file calls that a metadata call.

### Why is the prompt cache segment missing from my status line?

Prompt cache health needs Claude Code 2.1.251 or newer. On older versions the segment does not appear at all rather than showing an error, so a shorter status line on an old client is expected rather than a misconfiguration.

### How do I install usage on a machine without a menu bar?

The terminal interface runs anywhere through uvx usage-cli, Linux included, with no install step and no menu bar. On macOS the documented route is a Homebrew cask, and on Windows there is a tray application under the wintray directory.

### Which tools does the usage dashboard track?

Claude Code, Codex, Antigravity, Grok CLI and Muse Code. Antigravity, Grok CLI and Muse Code have their own statusline modules alongside the base one, and Muse Code contributes cost and token totals without getting a quota card because it keeps no local quota data.

### Can I pipe the usage numbers into my shell prompt?

Yes. The status --json command hands your Claude Code and Codex quota to any tool that can run a command, such as Starship or tmux, reading the same local files as the menu bar with no network call. Ready-made snippets are in the development documentation.

## Sources

- [aqua5230/usage on GitHub](https://github.com/aqua5230/usage)
- [License: AGPL-3.0](https://github.com/aqua5230/usage/blob/main/LICENSE)
- [Project website](https://aqua5230.github.io/usage/)
- [README](https://github.com/aqua5230/usage/blob/main/README.md)
- [Releases](https://github.com/aqua5230/usage/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/aqua5230-usage