Can I use aqua5230/usage commercially?

Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.

Is aqua5230/usage still maintained?

Yes. The repository last received commits 1 day ago.

What programming language is aqua5230/usage written in?

Mainly Python, according to GitHub's language statistics.

aqua5230/usage: Claude Code and Codex quota in the menu bar

At a glance

What is it?: A local-first quota monitor that reads Claude Code and Codex log files already on disk, plus a terminal interface via uvx usage-cli. The trade-off is that it is a viewer, not a reset button, and Antigravity is the one source that leaves the machine.
Who is it for?: Adopt it if you run Claude Code or Codex on macOS and want the 5-hour and weekly windows visible without opening a page, or on Linux if you only need the TUI through uvx usage-cli. Skip it if you are not a CLI-tool user, if you need Antigravity numbers to stay off the network, or if you expect it to raise your limits rather than describe them.
Can I use it commercially?: Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
Is it still maintained?: Yes. The repository last received commits 1 day ago.
What is it written in?: Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.

DEEP OPEN-SOURCE ANALYSIS

Hysen Labs Editorial · September 15, 2026 · aqua5230/usage

The problem is that quota is invisible until it is gone

Claude Code and Codex enforce rolling 5-hour windows and weekly caps, and neither puts a persistent meter in front of you. You find out you are out when a long refactor stops mid-file. The README frames the project around exactly that moment: running out mid-session is expensive, and the answer should be somewhere you already look rather than behind a command or a web page.

The audience is narrow and specific. It is developers who already live in the macOS menu bar or the Windows system tray and who use one or more of Claude Code, Codex, Antigravity and Grok CLI. If you do not run those tools, nothing here applies to you. The project is a monitor, not a proxy and not a quota manager: it does not route your requests or change your limits, it reports them.

Passive log reading, one network exception, and a status line hook

The core mechanism is file reading. Claude Code and Codex numbers are parsed from log files already on your machine, so the README states that watching your quota never calls Anthropic or OpenAI's LLM APIs and never costs a token. Grok CLI is also local: a fourth card reads its weekly credit percentage from its own debug log with no network call, and because Grok CLI exposes no session or burn-rate data the card shows a single weekly bar. Antigravity is the documented exception. Its quota comes from Google's official quota endpoint using the sign-in the Antigravity CLI already stores locally, described as a metadata call that does not consume model quota.

Around that core sit several separate processes visible in the repository layout. usage_statusline.py and its agy and grok siblings feed a status line segment inside Claude Code, including a prompt cache hit rate with a countdown to expiry, which requires Claude Code 2.1.251 or newer and silently does not appear on older versions. usage_statusline_forwarder.py and usage_client.py suggest a forwarding path between components. A daily background diagnosis scans logs for repeated file reads, polluter directories and noisy Bash output. Service status comes from public Statuspage.io pages for Claude Code, Claude API and Codex API, not from any usage API, and Antigravity is not covered because it has no public status page.

The design consequence is worth naming. Everything downstream of the log files is only as accurate as those files, and the project cannot see usage that never got logged locally. That is the price of not calling an API, and it is a reasonable price.

Installing usage-cli on macOS and getting a first reading

The README's quick start is a single Homebrew cask. It places the app in your Applications folder, and the README notes you right-click Open once to pass Gatekeeper before clicking the menu bar icon.

bash

brew install --cask aqua5230/usage/usage

On anything other than macOS, the terminal interface runs without an install through uvx. The README states it works on Linux too, with no menu bar.

bash

uvx usage-cli

The package is published as usage-cli on PyPI and declares Python 3.13 or newer in pyproject.toml. The macOS dependencies are the PyObjC frameworks for Cocoa, Quartz, UserNotifications and WebKit, so a source install on macOS pulls those in; the Windows tray path is an optional extra named windows that adds pystray, pillow, pywebview and windows-toasts.

For wiring the numbers into something else, the README points at a JSON mode. The command is `usage status --json`, which reads the same local files as the menu bar and makes no network call, and the README links ready-made snippets for Starship and tmux.

bash

usage status --json

After the first launch the README's setup flow includes the status line. That is a separate step from the menu bar, and the cache-health segment only appears if your Claude Code version is new enough.

Where usage is the wrong tool

It cannot help you if you are not running one of the four supported CLIs. Antigravity and Grok CLI support are described as reading specific local artifacts, and there is no generic adapter for arbitrary tools in the README, so a homegrown agent gets no card.

Antigravity also breaks the local-only story. Three of the four sources stay on disk, but Antigravity quota is fetched from Google's quota endpoint using the sign-in the Antigravity CLI stores. If your reason for wanting a quota monitor is that you do not want another process touching a provider endpoint, this is the part to read carefully. The README is upfront that it is a metadata call, but it is still a call.

Coverage gaps are documented rather than hidden. Antigravity has no service status banner because it has no public status page. Grok CLI has no session or burn-rate data, so its card is a single weekly bar. The prompt cache segment needs Claude Code 2.1.251 or newer and is absent otherwise. And the Token Saver feature, which asks Claude Code and Codex to answer more tersely, is a prompt-level intervention rather than a quota change; the README cites an A/B test on real sessions where late replies stayed about 40% shorter instead of drifting 84% longer, which is the project's own measurement and not something an outside party has reproduced here.

How it differs from a status line script or a provider dashboard

The obvious alternative is a hand-rolled status line that shells out to a log parser, and the difference is scope rather than mechanism. A script gives you one line inside one tool. usage runs a persistent process, keeps a menu bar or tray item, adds HTML reports with daily and weekly trends, project rankings, a contribution heatmap and a Year in Review, and exports to .html, .csv or .png offline with optional project-name masking. The status line is one output among several, not the product.

The other alternative is the provider's own dashboard. That is authoritative in a way a log parser is not, but it requires opening a page and it does not sit in the corner of your screen while you work. The README's whole argument is about that difference in attention cost. It is a fair argument, and it is also the reason the project can never be more accurate than the dashboards it approximates.

A third comparison is the terminal interface route. `uvx usage-cli` gives you the same readings without the menu bar, which is what makes the project usable on Linux at all. If you are on macOS and already have a status line you like, the TUI is the smaller commitment.

Licence, maintenance and the cost of upgrading

The licence is AGPL-3.0-only, declared both in the README badge and in pyproject.toml as `license = "AGPL-3.0-only"` with a LICENSE file. That matters if you plan to modify the code and distribute it or run a modified version as a network service, because the AGPL's source-availability terms reach network use in a way the GPL does not. Internal use of an unmodified copy is a different question, and this is not legal advice; read the LICENSE file and talk to counsel if you are embedding it in something you ship.

Maintenance is active by the only measure available here: the last push to main was on 2026-09-14, and releases v0.30.15, v0.30.14 and v0.30.13 landed on 2026-09-13, 2026-09-12 and 2026-09-11 respectively. That cadence cuts both ways. You get fixes quickly, and you also get a moving target, so pinning a version is reasonable if you depend on the JSON shape from `usage status --json` or on the structure of the exported reports.

Upgrade cost is mostly environmental. The project requires Python 3.13 or newer, and pyproject.toml carries a deliberate uv configuration listing darwin, win32 and linux environments with a comment explaining that without it a re-lock on Windows rewrites the darwin markers and drops PyObjC from the lock. Anyone maintaining a fork or building from source should keep that block intact. On macOS the Homebrew cask handles upgrades; on the uvx path you are re-resolving the package each run unless you pin it.

Editorial conclusion

Adopt it if you run Claude Code or Codex on macOS and want the 5-hour and weekly windows visible without opening a page, or on Linux if you only need the TUI through uvx usage-cli. Skip it if you are not a CLI-tool user, if you need Antigravity numbers to stay off the network, or if you expect it to raise your limits rather than describe them. Before trusting the cost column, check that pricing.py maps your model names and that project_resolver.py groups your sessions the way you expect.

Frequently asked questions

How do I add a usage bar in Claude Code with aqua5230/usage?

The project ships a status line integration rather than a bar inside the editor: usage_statusline.py and its agy and grok siblings render the segment, and the README's first-launch section covers setting the status line up. The prompt cache health segment only appears on Claude Code 2.1.251 or newer.

How do I use usage credits in Claude Code with this tool?

It does not spend or manage credits. The README describes it as a monitor that reads Claude Code and Codex numbers 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.

What is aqua5230/usage and what does it show?

It is a macOS menu bar and Windows system tray app that pins Claude Code, Codex, Antigravity and Grok CLI quota, burn rate and cost to your screen. Clicking the icon opens full session, weekly and per-project breakdowns, and it also produces shareable HTML reports.

Does aqua5230/usage work on Linux?

The menu bar and tray do not. The README states that `uvx usage-cli` runs the terminal interface anywhere, Linux included, with no install and no menu bar.

Does aqua5230/usage send my data to Anthropic or OpenAI?

The README states that Claude Code and Codex numbers are read passively from local log files and Grok CLI from its own debug log, so those never call the providers' LLM APIs. Antigravity is the documented exception: its quota comes from Google's official quota endpoint using the sign-in the Antigravity CLI already stores locally.

Official sources

Community notes