Skip to content

Installation

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

Installation

English · 简体中文

TokenTracker ships three install paths. All three share the same underlying tokentracker-cli npm package and the same ~/.tokentracker/ data directory — you can mix and match.

TL;DR

I want… Run this
Just try it — no permanent install npx tokentracker-cli
Command-line usage across projects npm i -g tokentracker-cli
macOS menu bar app + desktop widgets brew install --cask mm7894215/tokentracker/tokentracker
CLI via Homebrew instead of npm brew install mm7894215/tokentracker/tokentracker

Requirements

  • Node.js 20+ — the CLI uses features (fetch, readable-stream iteration, test runner) that need Node 20
  • macOS / Linux / Windows for the CLI — the Cursor SQLite reader and the menu bar app are macOS-only; other integrations work everywhere
  • Network is only required for the first npm install and any optional leaderboard sync. All token tracking itself is offline.

Check your Node version:

node --version

If it's < 20, upgrade via nvm, fnm, or your package manager (brew upgrade node, apt install nodejs, etc).

Paths in detail

1. npx (zero install)

npx tokentracker-cli

Downloads the package to npm's cache, runs it once, leaves no global binary. Good for trying it out. Subsequent npx invocations reuse the cache.

2. Global npm

npm i -g tokentracker-cli

tokentracker          # Opens the dashboard
tokentracker sync     # Manual sync
tokentracker status   # Integration status
tokentracker doctor   # Health check
tokentracker uninstall

Aliases also available: tracker, tokentracker-cli, tokentracker-tracker.

3. Homebrew (macOS)

Both a Cask (menu bar app) and a Formula (CLI) live in the homebrew-tokentracker tap. You don't need to brew tap first — brew install mm7894215/tokentracker/tokentracker handles that in one step.

# Menu bar app + CLI (recommended on macOS)
brew install --cask mm7894215/tokentracker/tokentracker
brew install mm7894215/tokentracker/tokentracker

# Upgrade
brew upgrade --cask mm7894215/tokentracker/tokentracker
brew upgrade mm7894215/tokentracker/tokentracker

The tap auto-updates within an hour of every new release (via a cron on the tap repo), so brew upgrade is all you need — no manual steps.

4. macOS DMG (standalone)

If you don't want Homebrew, grab TokenTrackerBar.dmg from the latest release and drag TokenTrackerBar.app into Applications.

First launch may hit Gatekeeper — see Troubleshooting → macOS App.

Linux / WSL notes

  • All integrations that use hooks or SQLite file paths work identically on Linux and WSL
  • The macOS menu bar app is Apple-only
  • The Cursor integration reads Cursor's local SQLite — on Linux that lives at ~/.config/Cursor/; on macOS at ~/Library/Application Support/Cursor/. TokenTracker detects both
  • WSL1 users: file watching across the Windows ↔ WSL boundary can be flaky; prefer running the CLI in pure WSL with your AI tools also in WSL

What gets written to disk

Location Contents
~/.tokentracker/ Queue, config, cached usage snapshots
~/.tokentracker/app/ (global install path for embedded helpers like the OpenClaw plugin — populated by init)
Hooks in each AI tool's config e.g. ~/.claude/settings.json, ~/.codex/config.toml
~/Library/Application Support/TokenTrackerBar/ (macOS app only) App preferences, widget snapshots via App Group

Running tokentracker uninstall removes all of the above and unhooks every AI tool.

Next steps

English

简体中文

Clone this wiki locally