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
Re-run the one-liner to update to the latest version, or git pull inside the repo directory if you cloned.
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.