Support

Getting started

It's asking me to choose a folderApp Store

The App Store build is sandboxed, which means it starts with access to nothing outside itself, including ~/.claude, where Claude Code keeps the logs. Click Choose your Claude folder, and the standard macOS picker opens on ~/.claude with hidden files already shown. Pick that folder (or projects inside it) and the meter fills within seconds.

You are asked once. macOS remembers the grant across relaunches and restarts, and it covers that folder alone. The app reads the logs there; the one thing it ever writes is a single entry in settings.json, and only if you install the gauge helper. Nothing leaves your Mac as a result of it. The direct download is not sandboxed and never asks.

Want to see what the app looks like before granting anything? The first-run card has a See a sample week button that fills every screen with clearly-labelled invented data. It is held in memory, never written to your history, and the same button dismisses it.

The meter is empty

BurnCast reads the logs Claude Code writes to ~/.claude/projects. If you have not run a Claude Code session on this Mac there is nothing to read yet. The meter fills within seconds of your first turn. If you have run sessions and it is still empty, check that the folder exists and contains .jsonl files.

The App Store build tells these two apart rather than guessing: a folder it has not been granted access to looks exactly like a folder that is empty, so it says choose your Claude folder in the first case and no sessions yet in the second. It will not claim Claude Code is missing when it simply cannot look.

I mostly use Claude on the web or in the chat app

Your usage still counts, and BurnCast can usually show it. Your plan's limits are shared across everything you use Claude for, so the app only needs one source on your Mac to read them from. It never connects to your account to do it: there is no networking code in the app at all.

If you use the Claude desktop app, leave its menu-bar icon switched on and the direct download reads your real figures from what it already keeps on disk, refreshed every fifteen minutes or so while it runs. The App Store build is sandboxed and cannot reach those files, so it needs the route below instead.

Otherwise, install Claude Code, sign in with the same account, and install the gauge helper. Each time you open Claude Code it reports your account's own percentages for the whole plan. Between opens the reading holds at the last sync, so opening Claude Code for a few seconds is the refresh.

I switched builds and my history is gone

Expected, and it repairs itself. The two builds keep their databases in different places, and the App Store build's lives inside its sandbox container, so a switch starts from an empty one. That database is only ever a reconstruction of your logs, though, and it rebuilds from them within seconds of the first scan. What does not carry over is the snooze state and any gauge readings, neither of which is worth moving.

It shows a dash instead of a number

A dash means the reading is not anchored yet: too little of the window has elapsed to judge a rate, or the app has no confirmed percentage to calibrate against. It resolves on its own after a few minutes of work. In the direct download, installing the gauge helper makes it resolve sooner and more precisely; the App Store build resolves it from your logs alone.

Reading the number

What does 1.4× mean?

It is tokens spent divided by time elapsed, inside the current five-hour window. 1.0× is even, meaning you spend your tokens exactly as the clock runs out. Above 1.0× you are ahead of the clock and will run dry early. Below it you are behind, and finishing the window with tokens unspent.

The bands are: under 0.9× is under pace, 0.9 to 1.05× is on pace, above 1.05× is over pace, and above 1.25× is overusing.

I'm under pace. Is that bad?

No, it is an opportunity. You are paying for capacity you are not using. Raise the model tier, turn effort up, or run a second Claude Code session alongside the one you have. The colour stays green because nothing is wrong; the number is telling you there is room.

I'm overusing. What should I actually change?

In order of least disruption: run fewer parallel sessions, lower the effort level, then drop a model tier. The app does this arithmetic for you. Open the popover and it names the smallest single change that lands you back inside the cap, and gives you the command to make it.

The percentage doesn't match what Claude Code tells me

The app estimates usage from token counts in your logs and calibrates against any limit notices it finds. That is a good estimate, but it is an estimate.

Installing the gauge helper goes one better: it shows your account's own figures instead of a reconstruction. Either build can do it; without it, the estimate sharpens as your history builds up.

Does it work with my plan?

Yes. The app reconstructs whichever windows apply to you: the rolling five-hour session window, the weekly window, and the separate weekly allowance for the largest model. It then tells you which one is the binding constraint right now.

The gauge helper

Where do I turn it on?

BurnCast asks the first time you open it. A setup window lists whatever stands between it and your account's real figures (folder access on the App Store build, Claude Code itself if it is not on this Mac, and the helper) and turns each one on in a click. Nothing is installed unless you press the button. If you closed that window, the same steps are behind Settings → Official usage gauge → Setup steps, and the Get exact figures chip in the menu-bar popover switches it on directly.

Will it break my existing status line?

No. If you already have a statusLine command configured, the installer chains ours ahead of it rather than replacing it: your command still runs, exactly as it did, and its output is still what you see. Your settings.json is backed up before the first change, and uninstalling restores the previous value exactly.

How do I remove it?

Settings → Official usage gauge → Remove helper. That restores your Claude Code configuration. You can then delete ~/Library/Application Support/BurnCast to remove everything else.

Settings says “conflict”

That means settings.json no longer points at the helper, usually because the status line was changed by hand or by another tool after installation. Clicking Reinstall helper resolves it, preserving whatever command is there now.

Alerts

I'm not getting notifications

macOS must grant permission first. Check System Settings → Notifications → BurnCast and make sure alerts are allowed. Note that level alerts (90% / 95% / 99%) deliberately wait until the app has your real account percentages, so they never guess from an estimate. That means either the gauge helper, which both builds ship and offer during setup, or the Claude desktop app on the direct download. Until one of those is in place you get pace warnings but not level ones.

Can I make it quieter?

Yes. Alerts can be snoozed from the notification itself, and level alerts can be switched off entirely in Settings. Pace alerts escalate with hysteresis, so sitting near a threshold will not notify you repeatedly.

Privacy and removal

Does it send anything anywhere?

No. The app contains no networking code at all. The privacy policy sets out exactly what is read and stored, and is specific about the two places data about you does exist: Apple's App Store records and this website's server log.

How do I completely uninstall it?

Remove the gauge helper from Settings if you installed it, quit the app, move it to the Trash, and delete ~/Library/Application Support/BurnCast (for the App Store build, ~/Library/Group Containers/63QYYU98T6.app.burncast and the app's container under ~/Library/Containers). Nothing is left behind, and your Claude Code logs are untouched, because the app never writes to them.

Still stuck

If the app itself looks wrong rather than the numbers, the download page has the checksum for the current build, the release notes, and the uninstall steps.

Email olmsteadbrett@gmail.com. Including your macOS version, whether you have the App Store or direct build, and whether the gauge helper is installed will usually get to an answer in one round trip. Please don't paste your prompts or your code: BurnCast never reads them, and this doesn't need them either.