ai-usage: AI provider quotas, always in sight

For months now, I have been working with AI agents in earnest: entire projects progressing through long sessions, crons that publish every night, and reviewers running in parallel. And yet, with everything in place, a new annoyance has appeared: usage windows. Providers limit usage within time windows, and when a window closes halfway through a task, the agent comes to a halt with a 429 error. This has happened to me so many times—there are entries in this site's journals that had to be recovered precisely because of this—that I ended up needing something very simple: to see each provider's usage in real time, always visible, without opening anything.

From this need grew ai-usage, a small program written in Go that queries the quotas for my three providers —Codex, MiniMax, and z.ai— and displays them in a compact line in the terminal or, even better, in the status bar of Term, the new plugin-enabled terminal I'm testing in beta, and for now I'm very happy with it.

From openusage to fuelcheck

The idea did not come out of thin air. For some time I've been using openusage, an application that brings the usage of AI services together in one place, and I asked myself why all of this could not live directly in the terminal, where I spend my day. Looking for a starting point, I found fuelcheck, a minimal project written in Go that did half the job: querying quotas and displaying them. I took it as a starting point and created my own repository, with the name that describes what it does: ai-usage.

What it does

• Three providers: Codex, MiniMax, and z.ai. Only the ones you declare and enable are queried.
• A common model: each API speaks its own language (MiniMax returns the remaining percentage per model; z.ai encodes windows with unit/number pairs), and the program normalizes everything into usage, window, and time remaining until the reset.
• Traffic light: green at 70% or more remaining quota, red below 35%.
• Adaptive layout: everything on one line if the terminal width allows; otherwise, one row per provider.
• Continuous mode: with --watch the widget stays fixed in a tmux panel and refreshes at regular intervals.
• Normalized JSON: with --json any script can read the quotas without having to interpret three different schemas.

The Term plugin

The part I am most excited about: Term (from Stencil) is a desktop terminal with plugins, still in beta, and I created a plugin of my own that displays the quotas in the bottom bar of the windows. It does not take up a terminal panel: it lives in the status bar, always visible. The integration has been tested with Term 0.9.12.

Go, after C

Go is an evolution of C, the language I learned at 42 Barcelona, and the transition has been quite natural: static types alongside the code, simple concurrency for querying the providers in parallel, and a single binary with no dependencies. Understanding the original project and adapting it was a matter of days, not weeks.

How I am building it

The method is the one I am already using on all my projects: first the domain vocabulary in a glossary, then a map of unknowns with child tickets, and the spec emerges from the facts uncovered by the research, not from opinions. Development is handled by oh my pi, the new harness I am testing, the same one used by Auto Magazine—and the results convince me. There is one detail that made me laugh: during a session, both subagent reviewers ran into a model usage limit. The tool that watches quotas got knocked over by a quota. It could not have been more timely.

The repository is private for now; when I decide to open it to the public, there is still a pending decision about cleaning up the history, which I have already documented. Once the project has matured a little more, it will have its page in the portfolio.