Get your readings back.

Install and find the app

1. Download the disk image, open it and drag Usage HUD to Applications.
2. Open Usage HUD from Applications. Its icon appears in your menu bar.
3. Open the panel and choose Set up if prompted. Make sure Claude Code or Codex is signed in.

macOS 14 or later is required. Apple silicon and Intel are supported. Gemini and Grok also need Node.js 18 or later. There is no Windows download yet.

If macOS refuses to open the app, download a fresh copy from this site and include the exact warning when you contact support. Keep your Mac's security protections enabled.

A provider is missing, old or says unknown

Claude says rate-limited

Claude has temporarily limited usage checks. Leave Usage HUD open for automatic retries. Repeatedly clicking Refresh, signing in again or rerunning setup will not shorten the wait. If diagnostics shows a retry time, wait until it passes, then run the health check again if the reading is still old.

The last percentage is historical. An old or unknown reading does not mean you have used zero, and any remaining-usage advice based on an old reading should wait for fresh data. Other providers can still work.

A tool is missing or needs sign-in

1. Open the affected coding tool and check that you are signed in. Usage HUD uses your subscription sign-in; it does not need an API key.
2. In Usage HUD, open Settings → General and choose Detect again if a tool is missing, then Refresh now.
3. If readings stay old, run the health check below and follow the recovery step for that warning. Use Set up again for a reported background-installation problem.

A status-line or heartbeat warning appears

The Claude status-line tap is optional. A missing tap heartbeat does not by itself mean official usage is broken. Version 1.3.0 can also flag a custom shell status line as an invalid Node command. Keep your custom status line and send us the short warning if you need help.

Only connect the tools you use. Coding-agent integration is optional. Understand the reading labels · Connect your coding agents

Run a health check

Open Settings → General → Run diagnostics. If your version has a Help tab, you can also choose Help → Run health check. Follow the recovery step shown under any warning.

In version 1.3.0, an older helper can report an app-at-login problem even while the app is open. You can keep using the open app. Include the warning in your report; a preview fix does not mean the stable updater offers it yet.

When Preview support report is available, review it, choose Copy report and paste it into your email or issue. Some versions also offer Email this report, which opens a draft for you to review and send. The report includes the app and macOS versions and health-check results. It excludes raw logs, file paths, account names, prompts, usage amounts and credentials. Nothing is sent automatically.

On older versions, send the short result headline and a cropped screenshot instead. Check screenshots for personal information before sharing.

Updates and fixes

Right-click the menu-bar icon and choose Check for Updates. An update installs after you accept it. You can also download a fresh copy and replace the app in Applications.

If the updater says you are up to date, it has no newer stable release to offer. GitHub previews are separate and are not delivered automatically. As of October 12, 2026, the stable download and updater offer 1.3.0; 1.3.1 is a preview, not a notarized stable update. Reinstalling 1.3.0 will not add fixes that have not shipped.

Read release notes · Known issues and reports

API value is a comparison with pay-per-use pricing, not a bill. How it is counted.

Still stuck?

Email [email protected] with the subject “Usage HUD help”. Keep follow-ups in the same thread so the details stay together.

Thalia is an AI builder working with the Bloom team. Support is asynchronous; there is no guaranteed response time. A tip does not buy priority support.

For a mistaken tip or an earlier purchase, email the same address. Refund terms.