A tiny macOS menu bar extra that shows how much of your weekly SuperGrok pool is used.
It reads the same billing total as grok.com Settings → Usage and keeps it in the top-right of the screen: Grok mark + 8%. Orange from 70%, red from 90%. Click the extra for the rest of the numbers and actions.
This is an unofficial personal tool. It is not affiliated with, endorsed by, or supported by xAI.
- Apple Silicon Mac (the binary is
arm64) - macOS 13 or later
- Grok CLI installed and signed in (
grok login)
The app does not have its own login. It reuses ~/.grok/auth.json and refreshes the OIDC token when it is about to expire.
git clone https://github.com/maxbobkov/grok-usage.git
cd grok-usage
make installThat builds an unsigned .app, copies it to ~/Applications/GrokUsage.app, and loads a LaunchAgent so it starts at login.
The first open may be blocked by Gatekeeper (ad-hoc signature, no Developer ID). Right-click the app → Open. After that the LaunchAgent is enough.
Check the live number without the menu extra:
make checkThe same weekly number can live on the Chrome toolbar. Chrome cannot read ~/.grok/auth.json, so the extension asks you to import that file once after grok login.
make check-extensionThen in Chrome: chrome://extensions → Developer mode → Load unpacked → chrome-extension/. Click the Grok mark and import ~/.grok/auth.json. Details are in chrome-extension/README.md.
make uninstallThere are two different percents. The one next to the Grok mark is weekly SuperGrok usage across surfaces (Grok Build, grok.com chat, Imagine, …). Week progress is how far you are through this week's usage window, by time (last reset → next reset).
| You see | Meaning |
|---|---|
8% |
Share of this week's SuperGrok pool already used (same total as grok.com Settings → Usage) |
| Orange | 70–89% of the weekly limit used |
| Red | 90–100% of the weekly limit used |
? |
No ~/.grok/auth.json, or the billing request failed |
Click the extra. The first block is status (not clickable). Then the actions.
| Line | Meaning |
|---|---|
Usage 8% |
Same weekly usage percent as the menu bar |
Resets 1 Sep 2026 06:34 |
When the weekly SuperGrok window ends and that usage percent goes back to 0% |
Renews 1 Sep 2026 |
When the current SuperGrok period ends and the next one starts. Shows Ends instead of Renews if auto-renew is off |
Week progress 43% |
How far this weekly limit window has run. 3 days into a 7-day window is 43%; 100% is the reset |
Updated 19:40 |
Clock time of the last successful fetch |
| (error text) | Shown only when the last refresh failed. The extra keeps the last good percent when it can |
| Action | Meaning |
|---|---|
| Refresh Now ⌘R | Fetch usage and subscription dates now, instead of waiting for the 5-minute poll |
| Open Usage ⌘O | Open the Grok usage page in the browser |
| About Grok Usage | Version, plus a link to the GitHub repo |
| Quit ⌘Q | Quit the extra. It does not relaunch until the next login, or until you open the app again |
Grok CLI has no grok usage command. The TUI fetches:
GET https://cli-chat-proxy.grok.com/v1/billing?format=credits
with the session token from ~/.grok/auth.json. This app calls the same endpoint and uses creditUsagePercent — the shared weekly pool that grok.com shows (Build, chat, Imagine, and the rest combined). SuperGrok renewal comes from GET https://grok.com/rest/subscriptions (billingPeriodEnd on the active subscription). Week progress is (now − weekly start) / (weekly end − weekly start) from currentPeriod on the billing payload (last reset → next reset).
That path is undocumented and can change without notice. If it breaks, the extra keeps the last good percent when it can, otherwise it shows ?.
Polling: every 5 minutes, at launch, on Mac wake, and when you hit Refresh.
Command Line Tools are enough. Full Xcode is not required.
make build # GrokUsage.app in the repo (gitignored)
make run
make installscripts/generate-icon.swift rebuilds Resources/AppIcon.png and Resources/AppIcon.icns from Resources/GrokMark.svg if you change the mark.
Tokens never leave your machine except as a Bearer header to xAI. The macOS extra does not log tokens, and they are not stored in the app bundle. ~/.grok/auth.json stays mode 0600. The Chrome extension keeps a copy of the imported token in Chrome local storage on this machine.
MIT. The Grok mark is used only to refer to Grok; it belongs to xAI.