Support

Getting started

The meter is empty

Tokenometer 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.

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. Installing the gauge helper makes it resolve sooner and more precisely.

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 — you will 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–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

Without the gauge helper 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. Install the helper (below) to display your account's actual figures.

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 — and tells you which one is the binding constraint right now.

The gauge helper

Will it break my existing status line?

No. If you already have a statusLine command configured, the installer wraps it rather than replacing it: your command still runs 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 gauge → Uninstall. That restores your Claude Code configuration. You can then delete ~/Library/Application Support/Tokenometer 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 Install again resolves it, preserving whatever command is there now.

Alerts

I'm not getting notifications

macOS must grant permission first. Check System Settings → Notifications → Tokenometer and make sure alerts are allowed. Note that level alerts (90% / 95% / 99%) deliberately require the gauge helper, so that they quote a real account percentage rather than guess from an estimate.

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?

Uninstall the gauge helper from Settings if you installed it, quit the app, move it to the Trash, and delete ~/Library/Application Support/Tokenometer. Nothing is left behind, and your Claude Code logs are untouched — the app never writes to them.

Still stuck

Email olmsteadbrett@gmail.com. Including your macOS version and whether the gauge helper is installed will usually get to an answer in one round trip.