tokentelemetry

Install and run the Claude Telemetry Enterprise console — a local-first FastAPI backend + React dashboard for Claude Code token/tool/skill/hook telemetry — as a global tool on Windows, macOS, and Linux, with Claude Code hooks wired up automatically.

The npm package bundles the backend, telemetry collector, hooks, and a pre-built copy of the dashboard, so once it's built, no separate git clone is required to run it.

Published on the npm registry — the fastest way to run it is npx, no clone required:

npx tokentelemetry

For daily use, install it globally instead so it doesn't re-resolve the package over the network on every run:

npm install -g tokentelemetry
tokentelemetry

Usage

tokentelemetry                    # install (first run) + start everything
tokentelemetry install            # copy app files, set up the Python env, wire Claude Code hooks
tokentelemetry start              # start the backend, telemetry daemon, and dashboard
tokentelemetry status             # show install location, running processes, health checks
tokentelemetry stop               # stop everything started by "start"
tokentelemetry autostart enable   # start automatically at login (Task Scheduler / launchd / systemd)
tokentelemetry autostart disable  # remove the autostart entry
tokentelemetry uninstall          # remove the Claude Code hooks (add --purge to also delete app files)

Then open http://127.0.0.1:5173.

None of the commands above rebuild or reinstall anything — each just does the one thing named.

Installing from source instead

For contributing, or to run a commit that hasn't been published yet:

git clone https://github.com/sarveshtalele/tokentelemetry.git
cd tokentelemetry
node cli/setup.js

This detects your system, builds + installs the global tokentelemetry command from this checkout (npm pack + npm install -g, not the registry), runs the app install, and drops you into an interactive Start/Stop/Status/Uninstall menu. Only bare node cli/setup.js (or node cli/setup.js install) does the full detect + build + install — the same fast subcommands work from the checkout too, and skip the rebuild:

node cli/setup.js start     # start the backend, daemon, and dashboard
node cli/setup.js stop      # stop everything
node cli/setup.js status    # show what's running
node cli/setup.js delete    # full teardown: remove hooks + ~/.tokentelemetry
node cli/setup.js uninstall # remove hooks only, keep app files/database (add --purge for delete's behavior)
node cli/setup.js install   # re-run the full build+install, e.g. after `git pull`

What "install" does

1. Copies the bundled backend/telemetry/hooks/dashboard into ~/.tokentelemetry (override with TOKENTELEMETRY_HOME).
2. Creates a Python virtual environment there, preferring uv when it's on PATH (falls back to the standard venv/pip), and installs the FastAPI backend's dependencies.
3. Merges the telemetry hook into your Claude Code settings (~/.claude/settings.json, or $CLAUDE_CONFIG_DIR/settings.json) for the SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, and Stop events — safe to re-run, entries are de-duplicated.

What "start" does

Runs three local processes (see tokentelemetry status for health/PIDs, and ~/.tokentelemetry/logs/ for their output):

• FastAPI backend on http://127.0.0.1:8000
• Telemetry reconcile daemon (polls Claude Code session transcripts)
• A static file server for the dashboard on http://127.0.0.1:5173

To have this run automatically every time you log in, run tokentelemetry autostart enable — it registers a Task Scheduler task (Windows), a launchd agent (macOS), or a systemd --user service (Linux) that runs start at login, using absolute paths so it works regardless of what the OS scheduler's PATH looks like. tokentelemetry autostart disable removes it, and tokentelemetry status shows whether it's on.

Requirements

• Node.js 18+ (to run npx)
• Python 3.9+ on PATH (or uv, which is preferred automatically when present)