Installation
Install TokenTelemetry with a one-line curl command, a Windows PowerShell script, or by cloning the repo.
Requirements
Before installing, make sure you have:
- Node.js 18+ — nodejs.org
- Python 3.9+ — python.org
- npm (comes with Node.js)
- At least one supported AI coding agent already installed (Claude Code, Gemini CLI, Codex, etc.)
Option 1: One-line installer (recommended)
The installer clones TokenTelemetry into a tokentelemetry/ folder in your current directory, sets up its Python and Node dependencies, and launches it automatically — your browser opens to the dashboard once it's ready.
macOS / Linux:
curl -fsSL https://tokentelemetry.com/install.sh | bashWindows (PowerShell):
irm https://tokentelemetry.com/install.ps1 | iexTo start it again later, run the launcher from inside the cloned folder:
cd tokentelemetry
./start.sh # macOS / Linux (or: node bin/cli.js)There is no global `tokentelemetry` command
TokenTelemetry runs from its own folder and deliberately installs nothing globally — it never touches your PATH. Always launch it with ./start.sh (or node bin/cli.js) from inside the tokentelemetry/ directory; typing tokentelemetry on its own will give command not found.
The dashboard is local-only
TokenTelemetry binds to 127.0.0.1, so the dashboard is reachable only from the same machine. To open it from another device (phone, another laptop, a VPS), set that up explicitly — see Remote Access.
Port already in use?
If you see required port(s) already in use: 3000, 8000, another process is on those ports. Free them (lsof -iTCP:3000 -sTCP:LISTEN shows the culprit) or start on different ports: ./start.sh --port 3100 --api-port 8100.
Option 2: Clone & run
Use this path if you want to hack on the source, pin to a specific commit, or inspect what you're running before executing it.
git clone https://github.com/VasiHemanth/tokentelemetry.git
cd tokentelemetry
./start.sh # macOS / Linuxstart.bat # WindowsOr cross-platform via Node:
node bin/cli.jsThe launcher creates a Python virtual environment and installs dependencies on first run. Subsequent starts skip the setup step if nothing has changed.
What gets installed
TokenTelemetry does not add any global npm package or modify your agent's config. It installs:
- A clone of the repo (or the release archive)
- A Python venv under
backend/venv/(created on first launch) - A
node_modules/folder underfrontend/(created on first launch) - A data directory at
~/.tokentelemetry/(created on first write)
Your agent logs are never modified — TokenTelemetry only reads them.
Updating
TokenTelemetry doesn't update itself — you pull the latest when you want it. The dashboard's update check (Settings → Updates & privacy) tells you when a new version is out; this is how you apply it:
cd tokentelemetry # the folder you installed into
git pull
./start.sh # start.bat on WindowsDependencies re-install automatically on the next launch when they've changed (a new lockfile or package.json), so there's no separate build step — git pull then start.
Re-running the one-line installer over an existing clone updates it too: it does a fast-forward git pull before launching. A manual git pull is the more predictable path, and the one to use if you've made local changes (the installer skips the update rather than clobber them).
Uninstalling
Stop TokenTelemetry (Ctrl+C), then remove the cloned folder (wherever you ran the installer) and the data directory:
# from the directory where you installed it:
rm -rf tokentelemetry ~/.tokentelemetryThat's everything — no system packages, no daemons, no registry entries.