Documentation

Three steps from an empty console to team-level spend and usage.

Tokenbar is an optional menu bar app for individual developers. It shows live provider limits, reset times, and usage forecasts. It is separate from the Tokenbase collector and does not replace the collector used for team telemetry.

It runs entirely on your Mac. Tokenbar reads your usage locally and talks directly to the providers you turn on, using the credentials already on that machine. Your usage never goes to Tokenbase. No account required: install it and it works on its own.

Linking a seat is optional. If your team uses Tokenbase, you can link Tokenbar to your seat. That makes a periodic read-only request to tokenbasehq.com for your organization name, team, and measured spend when priced data exists. Team spend appears only when the privacy cohort threshold is met. It only pulls that context down. It never sends your Mac's provider usage up, and nothing links unless you ask it to.

The universal app runs on Apple silicon and Intel Macs with macOS 14 or later. It is signed, notarized by Apple, and includes automatic updates.

Open the DMG, drag Tokenbar to Applications, and launch it. Then open Settings → Providers in Tokenbar and enable the services you use.

For more than a machine or two, make one enrollment key and reuse it everywhere instead of approving each machine in a browser.

In the console, open Connections, create an enrollment key, and turn on Reusable so the same key works on every machine. Then run this on each one: it installs, links, and starts the collector, with nothing to approve.

Deploy it however you provision machines. Drop the command into your device-management tool (Jamf, Intune), an Ansible playbook, or the image your CI builds from.

Two switches if you need them:

TOKENBASE_NO_SERVICE=1 installs and links without starting it in the background, for images that run the collector themselves.

TOKENBASE_NO_ENROLL=1 installs only, so you can link it later with tokenbase login.

Safe to run again. The installer checks the current state first and only does the work that is missing, so wrapping it in Ansible, Chef, or Puppet will not churn. Pass --check for a dry run that reports what would change without touching anything.

Headless servers. A per-user background service stops at logout and will not start at boot. After the install, register a boot-persistent system service instead:

Verify what you run. Before installing, the script checks the download's signature and checksum against a key built into the collector, and the macOS build is notarized by Apple. To serve the binaries from your own copy, which is useful on networks with no direct internet access, point TOKENBASE_INSTALL_BASE at an internal mirror.

Keep the key out of logs. Rather than putting the enrollment key in the command, set TOKENBASE_AUTH_KEY_FILE to a path your secret manager mounts. The key is read from the file, so it never appears on a command line, in shell history, or in your tooling's logs:

Rotate and revoke. Keys expire automatically (30 days by default; set a longer window when you create one). Once a rollout is done, rotate a key in Connections to mint a replacement and retire the old secret, or revoke it outright. A reusable key is a standing credential, so treat it like one. Behind a proxy, the installer follows the usual HTTPS_PROXY setting.

What leaves the machine. Metadata only by default: token counts, models, hashed paths, and the machine name your device reports at enrollment, never your source or message text. Run tokenbase preview on a machine to see the exact bytes before anything is sent.

A signed, device-scoped binary tails the local session logs your AI coding agents already write: read-only, incremental, checkpointed by offset. It enrolls as a device with its own scoped credential and never depends on a live browser session. It is never in the model request path.

Metadata-only is the default. A local preview shows exactly what would be sent before anything leaves the machine.

There's one reader per agent, each versioned and tested against captured real session logs. Every reader reports how much of an agent's data it covers and flags anything it doesn't recognize; if one reader breaks, the rest keep working. v1 reads Claude Code and Codex CLI fully, Copilot CLI (real token counts and premium-request usage are read from the session log; cost is estimated, since Copilot bills by premium requests rather than tokens), and Cursor (in beta; its local storage was worked out by inspection, so its coverage is labeled rather than assumed).

Tier A is factual (straight from logs): tokens, models, session counts, tool calls, cache reuse, model mix, and estimated cost. Tier B is inferred (heuristics on local data): abandonment, retry loops, likely task type, and is always labeled as inferred, never presented as fact.

Four modes, from fully managed to zero-egress:

SaaS, metadata-only. The default. Only metadata leaves the machine.

SaaS, redacted-text. Opt-in. Redacted transcript text leaves the machine.

VPC / on-prem. Zero-egress: raw transcripts never leave your infrastructure; analysis runs against a VPC model.

Local-only pilot. Zero-egress: raw transcripts never leave the device; analysis runs against a local model.