Quota Desk User Guide
Installing, connecting each service, reading the gauges, settings, and troubleshooting, in order. The app interface is in Japanese; Japanese labels are quoted where it helps.
Follow the steps in order, and the widget will be on your desktop.
Getting started
Quota Desk reads the usage limits of Codex, Claude, and Antigravity and shows what is left, and when it resets, in the app window and in desktop widgets.
Read from each service
Quota values come from the official Codex and Antigravity tools running on this Mac, the Claude Code status line, or the usage page on claude.ai. It never sends questions to an AI to estimate usage.
The app collects them
Values and history are stored on this Mac. Queries run every 5 minutes and whenever a service starts or stops.
Widgets display them
Desktop widgets show the values collected by the app.
- A Mac with Apple silicon (macOS 14 or later)
- An account for the services you use: Codex, Claude, or Antigravity
Basics
Install and launch
Open the downloaded
QuotaDesk-0.2.0.dmg, drag Quota Desk to the Applications folder, and launch it. The app window shows cards for Codex, Claude, and Antigravity.Place the widget
Right-click an empty area of the desktop and choose “Edit Widgets.” Select Quota Desk, then drag the triple-gauge widget (“Quota Desk · 3連メーター”) or a per-service widget onto the desktop in medium or large size.
Connect Codex
Use Codex CLI in your terminal as usual, or launch the Codex or ChatGPT desktop app. Quota Desk checks about every 10 seconds and reads the quota once it finds Codex running. No setup is needed.
MeiFor Claude, you can choose between two ways to connect.
Connect Claude
If you use the desktop app or a browser: in Settings, under “Claude Web連携” (Claude Web integration), click “Webアカウントに接続・確認…” and sign in with the same account you use in the Claude desktop app. Sign-in data stays in storage used only by this app.
If you use Claude Code in the terminal: in Settings, under “Claude Code連携（ターミナル版）,” click “ステータス行に接続” (connect to the status line). This edits Claude Code’s status line setting (
~/.claude/settings.json) and keeps your existing status command. A value arrives each time Claude Code finishes a response. “連携を解除” (disconnect) restores the original setting.Connect Antigravity
CLI (agy): if
agy1.1.11 or later is installed, Quota Desk queries the quota automatically.Desktop app or IDE: in Settings, under “Antigravity デスクトップ連携,” turn on “ローカル接続情報の利用を許可” (allow use of local connection info). Quota Desk reads the connection details from the running Antigravity and queries the quota within this Mac. Those details are kept only in memory and are never saved or sent anywhere.
Reading the gauges
Unknown values are never filled in by guesswork; retrieved values are shown as they are.
Needle and large number
With the default “short window first” setting, the 5-hour quota is shown if there is one; otherwise the weekly quota, and otherwise any per-model quota that was retrieved. If there are several of the same kind, the one with less remaining is shown.
Inner ring
If the same account and model group has a weekly quota, it appears as the inner ring with a weekly percentage. Weekly-only quotas use a single ring.
Reset time
Shown below the gauge for the main quota. If unknown, the gauge says it cannot be retrieved; after the time has passed, it shows that it is waiting for a new value.
White ◇ (1-hour forecast)
Shown on the large widget only when there are at least 15 minutes and 4 points of history. It estimates what will be left in an hour at your current pace.
“—” and previous readings
No data shows “—,” which is different from 0%. Values older than 15 minutes are labeled as previous readings, and the gauge arc turns dotted.
Charts in the app
Solid lines are retrieved values; dashed lines are forecasts at the current pace. Periods before retrieval started are not filled in.
The app’s activity section shows the project name, model, reasoning setting, and state (running, waiting, and so on) of conversations in Codex, Claude Code, and Antigravity, about every 10 seconds. For Codex, up to 40 of the most recent conversations from the last 2 days are covered. Conversation text and prompts are not saved.
Settings
Open them from “設定とウィジェット” (Settings and widgets) in the app.
| Section | What it does |
|---|---|
| App updates | Turn automatic checks at launch and periodically on or off, and check for updates now |
| Services to show | Choose which of Codex, Claude, and Antigravity to show |
| Retrieval method | Choose the source for each service. “Automatic” re-detects the running source about every 10 seconds. You can also show cards for services that are not running |
| Antigravity desktop integration | Allow or disallow use of local connection info |
| Claude Web integration | Connect and verify the web account, or disconnect |
| Claude Code integration (terminal) | Connect to the status line, or disconnect |
| Retrieval and history | Clear saved history and start recording again for the current account |
| Widget target | Right-click a widget and choose “Edit Widget” to pick short window first, 5-hour, or weekly. Choosing weekly shows a single ring |
Troubleshooting
MeiFirst, keep the app running and wait a moment.
Quota Desk does not appear in the widget list
Close the widget editor, launch Quota Desk, and then open “Edit Widgets” again.
Claude stays “connected, waiting to receive”
With the terminal version, ask Claude Code something as usual and wait for the response to finish; the value arrives then. If nothing appears, restart Claude Code and check that a project-level setting does not override the status line. If you mainly use the desktop app, the Claude Web integration is recommended.
No quota for the Antigravity desktop app
Check that “allow use of local connection info” is on under the Antigravity desktop integration in Settings. When it is off, only the CLI (agy) is used.
Old values appear mixed in after switching accounts
In Settings, under retrieval and history, clear the history and start recording again.
Values are labeled as previous readings
No new value has been retrieved for more than 15 minutes. Check that the app and each service are running. Retrieval stops when you quit the app.
Will opening the app repeatedly start it twice?
No. However many times you open it from a widget or the menu bar, the existing window comes to the front.
A confirmation screen appears the first time
macOS shows it the first time you open an app downloaded from the internet. Choose “Open.” You can check that the file is official by following Verifying the download.
Glossary
| Quota | The amount you can use in a set period under your AI service plan. |
|---|---|
| 5-hour / weekly quota | The length of the counting period. The usable amount comes back every 5 hours or every week. |
| Reset | When usage is counted afresh and the quota comes back. |
| CLI | A tool you use by typing in a terminal, such as Codex CLI or Antigravity’s agy. |
| Status line | The one-line display at the bottom of Claude Code. Quota Desk receives quota values from it. |
| Notarization | Apple’s automated check of distributed apps for known malware. |
How it works in more detail
- Codex quotas come from the read-only endpoint of Codex CLI (
account/rateLimits/read; the desktop app uses its bundled CLI). Antigravity quotas come fromagy -p /usageor from Antigravity’s endpoint running on this Mac. - The app and widgets exchange values through
dashboard.jsonin a macOS shared folder (App Group). Widgets never launch CLIs or handle sign-in. - A per-user lock file prevents the app from running twice.
- Updates use Sparkle 2.10.0, which verifies the Ed25519 signatures of the update feed and DMG before replacing the app.