Documentation

Three steps from an empty console to usage and cost estimates.

Tracked usage cost is an estimate from API list rates, with agent-reported cost used when a rate is unavailable. It excludes unpriced activity and is separate from your provider invoices, subscriptions, credits, and discounts.

A known token count multiplied by a known API rate is still a usage estimate. A subscription can cover that activity for a different flat price. Copilot credits and premium requests are billing units, not dollars. An unavailable cost means we cannot price the activity; it does not mean the activity was free.

Add a provider plan in its agent page to compare usage with the monthly price you declare. The comparison uses observed active people as an estimated seat count, with a minimum of one. It does not know how many seats you purchased and does not reconcile invoices. A lower usage estimate is not automatically money saved or evidence of higher productivity.

Paid Tokenbase bands use the average tracked usage cost over the last three complete calendar months. Crossing a band produces an in-product reminder; it does not stop collection or change your subscription automatically.

On Overview, choose a date range and select Download cost review. The Markdown file contains estimated usage costs by agent and model, pricing gaps, a projection when enough history exists, and workflow findings with next steps. It is downloaded locally and does not create a public link.

Reviews require the organization's minimum number of active developers in the selected range and a completed import. Individual usage and numerical team allocations are omitted to protect small cohorts. Team totals elsewhere cover all recorded history; budget checks use the current calendar month.

Add provider invoices for matching dates before making a budget or renewal decision. Record the action, owner, and review date. Compare actual bills and workflow results next time; lower estimated usage alone does not establish cash savings.

Open Billing in your workspace to see its current member count and configured member limit. No per-seat pricing does not mean unlimited membership, and choosing a paid plan does not by itself raise the limit. Member capacity is separate from enrolled devices.

Before purchasing for a larger team, contact us to confirm capacity. Then start with the coding agents and machines that matter to your next budget or renewal decision. Usage from machines that have not enrolled is missing from your report.

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, estimated usage cost when priced data exists, and weekly session-ending labels when you enabled them in the collector. Those labels describe what messages claim, including unclear results; they do not prove that work or checks completed. Team totals appear 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. Token and cost coverage differ by agent and by the data present in each session.

Tier A is factual (straight from logs): tokens, models, session counts, tool calls, cache reuse, and model mix. Dollar figures are estimates of usage cost, even when the tokens and rate are known. Tier B is inferred (heuristics on local data): abandonment, retry loops, likely task type, and is always labeled as inferred, never presented as fact.

The setup above runs a collector on each enrolled machine and sends usage metadata to your hosted Tokenbase workspace. Reading and extracting session metadata happens locally; the workspace combines it for team reports. Run the local preview before enrollment to inspect what will be sent.

Optional session labels are off by default and enabled per device. If enabled, the collector sends a clipped, credential-redacted excerpt to TypeSafe using your API key. Tokenbase receives only typed labels about work kind and closing claims. Those labels describe what the messages say; they do not verify that the work or checks succeeded.

Tokenbar is a separate local utility. It can show provider usage on your Mac without an account, but it does not provide the hosted team reports. If your organization needs a private-network deployment or custom data processing terms, discuss those requirements with us before planning a rollout.