Skip to content
Viberia Docs

Token Tracker

The Token Tracker is a small widget anchored to the bottom-right of the screen that shows your current token usage broken out by provider, with a configurable refresh interval and a list of which providers to display.

How It Works

Section titled “How It Works”

The Token Tracker reads usage from each configured CLI provider — Claude, Codex, Gemini — and renders one row per provider in a compact widget. Each row shows the provider’s name, a gauge of recent usage, and the most recent refresh timestamp. The widget polls the provider CLI in the background on a schedule you set and updates the rows in place when new numbers arrive.

The widget is toggled with the Cmd+Shift+U keyboard shortcut: press Cmd+Shift+U anywhere in the app to show it, press it again to hide. When hidden, the widget pulls completely off screen and stops polling. When shown, polling resumes immediately and the first refresh fires right away so the values are current.

Settings for the tracker live in Settings → Usage Tracker:

  • Enable Token Tracker — master toggle. When off, the widget is hidden permanently and Cmd+Shift+U does nothing.
  • Refresh interval — how often the widget polls each provider in the background. Shorter intervals are more accurate; longer intervals are cheaper.
  • Providers shown — pick which configured providers appear in the widget. If you only use Claude, hide the others.
  • Manual refresh — a button on each row triggers an immediate refresh for that provider without waiting for the interval.

The first time you enable the tracker, an onboarding popover explains what’s being shown and asks for consent if your CLI provider needs to be invoked to retrieve usage. You can dismiss the popover or grant consent; consent is remembered across sessions.

UI Indicators

Section titled “UI Indicators”
  • Provider rows — one per provider showing name, gauge, and last-refreshed timestamp.
  • Gauge fill — a horizontal bar that fills as you approach your provider’s plan limit (when the CLI exposes a limit).
  • Refresh spinner on each row while a poll is in flight.
  • Consent pill prompts you to enable polling for a provider that hasn’t yet been authorized.
  • Onboarding popover appears the first time you enable the widget.
  • Keyboard hint — pressing Cmd+Shift+U while the widget is hidden surfaces a faint reminder in the corner.

Use Cases

Section titled “Use Cases”
  • Watch a heavy session in real time. Open the widget before kicking off a long Council or Loop and keep an eye on usage as it climbs.
  • Compare providers. Run the same task on Claude and Codex, then check the tracker to see which one was cheaper.
  • Throttle yourself. When a gauge gets high, slow down or switch the responsible agent to a lighter model via its Model mode cell.
  • Hide it when you don’t care. Press Cmd+Shift+U to dismiss the widget and reclaim corner space.

Limitations

Section titled “Limitations”
  • The tracker reflects what each provider’s CLI reports. If a provider doesn’t expose usage data via its CLI, the row shows a placeholder and the gauge stays empty.
  • Refresh isn’t instantaneous — counts update on the configured interval. Click the manual refresh button for a fresh read.
  • The widget shows provider-wide usage, not per-agent usage. To attribute spend to a specific agent, look at that agent’s chat history or context badge.
  • Disabling the tracker stops polling entirely. Usage continues to accrue at the provider; you just won’t see it in this widget.
Section titled “Related”