Skip to content

FAQ

Jump to bottom
Rynn edited this page Apr 24, 2026 · 1 revision

FAQ

English · 简体中文

General

Is TokenTracker free?

Yes. MIT license, zero paid tiers. If it saves you time, starring the repo helps other devs find it.

Do I need a cloud account?

No. All token tracking is fully local — no account, no API keys, no network calls. The leaderboard is the only feature that requires signing in, and it's strictly opt-in.

What data is uploaded if I opt into the leaderboard?

Aggregated token counts + timestamps + the model name + cost estimates. No prompt content, no responses, no file contents — the local parser never reads them to begin with. See src/lib/rollout.js if you want to audit.

Does TokenTracker slow down my AI tools?

No. Hooks run at session-end only, do a few hundred ms of log parsing on a background Node process, and write a small JSON row. The AI CLIs don't wait on us.

Which platforms?

  • CLI + dashboard: macOS, Linux, Windows (Node 20+)
  • Menu bar app + desktop widgets: macOS only (Monterey 12 and newer)

Accuracy

Why is my cost slightly different from the provider's official bill?

Two reasons:

  1. Timing: TokenTracker aggregates into 30-minute UTC buckets. Your provider may bill in different intervals/timezones
  2. Pricing table: we keep a table of 70+ models with public prices. If a model isn't in our table yet (very new releases), we fall back to the closest family price. Open an issue if you spot a missing model

Usually the delta is < 1%. If you see > 5%, please report with tokentracker diagnostics output.

How does TokenTracker handle cache tokens?

Four token categories are tracked separately, all included in total_tokens:

  • input_tokens — pure non-cached input
  • cached_input_tokens — cache reads
  • cache_creation_input_tokens — cache writes
  • output_tokens — generated output
  • reasoning_output_tokens — reasoning tokens for reasoning-capable models

This matches ccusage's convention so numbers line up if you cross-check.

Gotcha: Codex / Every Code report input_tokens as cache-inclusive. Our normalizer subtracts the cached portion so cost doesn't inflate 6–7× on cache-heavy sessions. If you fork the parser, remember this.

Privacy

Can I see what TokenTracker records before enabling anything?

Yes — dry-run mode is the default for the first launch until you explicitly opt in to hook installation. Also:

tokentracker diagnostics > /tmp/tt.json

Dumps everything it knows about your machine (paths, integration state, queue contents) in JSON. No prompt content, no file contents, no secrets — just token counts, timestamps, model names, and config flags.

Does the macOS app send any telemetry?

No. No analytics, no crash reports, no phone-home. The only network activity is the embedded Node server talking to your local AI tools' own files, plus — if you opt in — the cloud leaderboard sync.

How do I completely wipe everything?

tokentracker uninstall

Removes every hook across all detected tools + ~/.tokentracker/. On macOS, also uninstall the app: brew uninstall --cask mm7894215/tokentracker/tokentracker or drag TokenTrackerBar.app to Trash.

Usage

How do I add a new AI tool that isn't supported yet?

Open an issue with the tool's log format (or a sample file), and we'll scope the parser. Contributions are very welcome — most new providers are a single file under src/lib/.

Can I self-host the leaderboard?

The leaderboard runs on InsForge Edge Functions. The code isn't open-sourced today, but the local CLI doesn't require it — you can use TokenTracker entirely offline. If self-hosting is important for you, open an issue to express interest.

I want the menu bar app without the dashboard in WKWebView

The app and the dashboard share one binary today — the menu bar pops a native panel (SwiftUI), the "Open Dashboard" action opens the WKWebView window. If you never use that window, nothing is loaded until you click.

Can I use TokenTracker with multiple machines?

Each machine tracks independently by default. If you opt into cloud sync, your usage from all signed-in devices rolls up under one account for the leaderboard. There's currently no "sync my local snapshot across devices" — the dashboard always shows this machine's data.

Releases & versioning

How often do you release?

Whenever a meaningful fix or feature lands — roughly weekly. See CHANGELOG / Releases.

Do CLI and macOS app share a version number?

Yes. package.json (npm) and TokenTrackerBar/project.yml (MARKETING_VERSION) are bumped together. Homebrew formula + cask both track the same version via an auto-update bot on the tap repo.

How do I update?

  • npm global: npm update -g tokentracker-cli
  • Homebrew: brew upgrade mm7894215/tokentracker/tokentracker (and the --cask variant for the macOS app)
  • macOS app auto-update: the app checks GitHub Releases hourly in the background and prompts when a new DMG is available

English

简体中文

Clone this wiki locally