usage CLI
A limits and token spend monitor for Claude Code, Codex, Antigravity and Grok CLI: macOS menu bar, Windows tray, HTML reports
- 345 ★ on the repository
- Last commit
- AGPL-3.0
Extended access
Why this level
- The setup button edits the configuration of Claude Code, Antigravity CLI and Grok CLI by installing a hook and a status line
- The app reads local session logs and the stored Antigravity sign-in and polls Muse Code with a background model call
Install
- Works in
Manual install
brew install --cask aqua5230/usage/usageThe recommended path for macOS 12 or newer; brew upgrade --cask usage keeps it current.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The setup button edits the configuration of Claude Code, Antigravity CLI and Grok CLI by installing a hook and a status line
- The app reads local session logs and the stored Antigravity sign-in and polls Muse Code with a background model call
This is third-party code. Review the repository files before installing.
What it does
usage shows the five-hour and weekly limits of Claude Code, Codex, Antigravity, Grok CLI and Muse Code in the macOS menu bar or the Windows system tray. A quota turns red as it nears the limit, and a click opens a breakdown by session, week and project. The app takes tokens and cost for Claude Code, Codex, Grok CLI and Muse Code from local logs. It reads the Antigravity quota through its CLI or through Google's official endpoint using the sign-in the CLI already stores. In Claude Code, the Set Up Status Line button installs a sync hook and a status line with warnings about a bloated context and a prompt cache miss. The app first backs up an existing status line and restores it when you turn the switch off. You can also enable a side pane with quotas and parallel conversations, the Token Saver shorter-replies mode and HTML reports for days and weeks, exported as html, csv or png. For terminals and scripts, usage status --json hands the quotas to Starship or tmux.
Who it is for. People who use Claude Code and Codex on a subscription and want advance notice before the five-hour window or the weekly limit runs out.
Good fit when
- A long refactor runs for hours and you do not want to hit a limit halfway through
- Claude Code, Codex and Antigravity run side by side and each remaining quota lives in a different place
- Sessions drag on with a cold prompt cache or a bloated context, and the status line suggests when to run /clear or /compact
- You want a weekly token and cost report by project, with project names optionally masked
- You want the quota in Starship, tmux or your own script through usage status --json
Not a fit when
- You only need a cost report without live limits: a console token counter is simpler for that
- The computer has no Claude Code, Codex, Antigravity, Grok CLI or Muse Code data and Claude Desktop is not running
- You want a menu bar app on Linux: only the terminal interface through uvx usage-cli is available there
- Company policy forbids AGPL-3.0 software or apps not signed by Apple and Microsoft
Example request
Run usage through uvx, show the Claude Code and Codex quotas with usage status --json and tell me whether the weekly limit will lastLimitations
- The app runs on macOS 12 or newer and Windows 10 or 11. On Linux only the terminal interface is available, without a menu bar or tray.
- Builds are unsigned: macOS 15 requires clicking Open Anyway in privacy settings, and Windows SmartScreen shows a warning.
- It needs data from at least one tool: Claude Code, Codex, Antigravity, Grok CLI, Muse Code or a running Claude Desktop app.
- The Muse Code quota comes from a small background model call through its CLI. Beginner Mode spends a little Claude quota, and auto-start of the five-hour window sends each tool a short message.
How to disable. The Sync quota via status line switch in Settings, under Claude Code, stops syncing and restores the previous status line. The app itself is quit and removed like any program: usage.app from Applications on macOS, the folder with usage.exe on Windows.
FAQ
How do I install usage on macOS?
Run brew install --cask aqua5230/usage/usage. You can also download usage.app.zip from the latest release and drag the app into Applications. If macOS blocks the first launch, open System Settings, Privacy and Security and click Open Anyway.
Where does usage get its limit data?
The app computes tokens and cost for Claude Code, Codex, Grok CLI and Muse Code from local logs. A status line hook syncs the Claude quota. It gets the Antigravity quota from its CLI or from a Google endpoint using the stored sign-in. There is no telemetry; by the author's account everything runs locally.
What does the Set Up Status Line button do?
It installs a quota sync hook and a status line in Claude Code. If you already configured your own line, the app backs it up and restores it when you turn the switch off. After pressing it, restart Claude Code, and on macOS quit it fully with Cmd+Q.
Can I get the quotas in Starship or tmux?
Yes, usage status --json prints the Claude Code, Codex, Antigravity, Grok and Muse quotas as JSON for Starship, tmux or your own scripts. Ready snippets live in docs/DEVELOPMENT.md.
Which systems does usage support?
macOS 12 or newer and Windows 10 or 11 with an app in the menu bar or tray. On Linux only the terminal interface through uvx usage-cli is available. It needs data from at least one of Claude Code, Codex, Antigravity, Grok CLI, Muse Code or a running Claude Desktop.
Discussion
No questions or reviews yet.
Related
CLI toolsA real-time terminal monitor for Claude Code usage: tokens, messages and cost in the five-hour window, with forecasts and export
A Claude Code plugin: a status line with context, 5-hour and 7-day limits, cost and usage of Codex, Gemini and z.ai
Token and cost reports for Claude Code, Codex, Gemini CLI and other agents from local logs, by day, month and session
Counts token use and cost of Claude Code and Codex sessions from local logs and shows remaining limits in the status line
A Claude Code status line showing 5-hour and 7-day quota use plus the pace: whether what is left lasts until the window resets
28 components, up to nine lines and 227 settings: a Claude Code status panel with tokens, cache and session price.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| usage (this card) | no | 345 | |
| ccusage | no | 19,349 | prints token and cost reports in the terminal, with no tray and no live window limits |
| claude-dashboard | no | 585 | a plugin with a status line inside Claude Code, not a standalone app |
README in short
The README starts from the idea of seeing limits in advance and lists five modes: menu bar, tool cards, warnings, helpers inside Claude Code and reports. It then covers installation through Homebrew, a portable Windows build and running through uvx. Next come the status line setup, a gallery of 16 themes, the side pane and a comparison table with other monitors.