Local observability for AI coding agents AND autonomous agents — Claude Code, Codex, Gemini CLI, Cursor, Copilot, Qwen, OpenCode, Vibe, Antigravity, Grok Build, and Nous Research's Hermes Agent.

Token Telemetry (one word: TokenTelemetry) — free, open-source, 100% local.

☤ New: Dedicated Hermes Agent dashboard — autonomous-agent observability across 38 platforms (CLI, Telegram, Discord, cron, webhook, …).

TokenTelemetry is a free, open-source, 100% local observability dashboard that tracks token usage, LLM costs, tool calls, session traces, and reasoning steps across all your AI coding agents — in one unified place. No signup. No cloud. No telemetry.

🌐 Website & Docs: https://tokentelemetry.com
🖥️ macOS/Linux: curl -fsSL https://raw.githubusercontent.com/VasiHemanth/tokentelemetry/main/install.sh | bash 🧰 Windows: irm https://raw.githubusercontent.com/VasiHemanth/tokentelemetry/main/install.ps1 | iex 🐙 GitHub: github.com/VasiHemanth/tokentelemetry

AI coding agents like Claude Code, Gemini CLI, and Codex are powerful — but they burn through tokens fast. How many tokens did that refactor cost? Which agent is most efficient? What did it actually do?

TokenTelemetry answers all of that — locally, instantly, for free.

TokenTelemetry reads session logs from these agents automatically.

More agents added regularly. Request support for your agent →

Hermes Agent isn't a coding agent — it runs across CLI, messaging platforms (Telegram, Discord, Slack, Feishu, …), scheduled jobs, and webhooks. It gets its own surface at /hermes with:

• 38 source platforms — every value Hermes emits in sessions.source
• Per-API-call latency + cache hit % parsed from agent.log
• Inline delegate_task subagent cards with summary, tokens, duration
• Skills + memory pages, cron health, gateway health, cost anomaly detection
• Provider-aware pricing — same model priced correctly across direct / OpenRouter / Together / Fireworks

Run TokenTelemetry on the same host as Hermes — we read $HERMES_HOME (or ~/.hermes/ if unset) locally, no remote-DB mode yet.

If you run Hermes's own web dashboard (hermes dashboard, port 9119), install the plugin so TokenTelemetry shows up as a tab inside it — one port to remember, deep-link cards to every TT page.

Standalone install (recommended — uses Hermes's own plugin manager):

hermes plugins install VasiHemanth/tokentelemetry-hermes-plugin
hermes dashboard

From this repo (canonical source, useful if you're hacking on the plugin):

./scripts/install-hermes-plugin.sh
hermes dashboard

The launcher tab works for every TT page, not just /hermes — Analytics, Projects, and All Agents views all open from inside Hermes Dashboard. Pure-frontend, no extra backend, no network access beyond your local TT. See plugin/hermes-dashboard/README.md for details.

• ☤ Hermes Agent dashboard — autonomous-agent observability at /hermes (38 source platforms, gateway health, cron jobs, skills, memory, subagent cards — see the section above)
• 📊 Token Usage Dashboard — real-time tokens in/out per agent, model, and project
• 💰 Cost Tracking — see exact LLM API costs per session and cumulative over time
• 🔍 Session Traces — waterfall view of prompts, reasoning chains, tool calls, and responses
• 🛠️ Tool Call Analytics — which tools your agents call most, success/failure rates
• 📁 Per-Project Insights — heatmap, activity timeline, agent leaderboard per codebase
• 🧠 Plan Capture — view plan-mode outputs from Claude Code and other agents
• 📈 Model Analytics — compare GPT-5.4 vs Claude 4.6 Sonnet vs Gemini 3.1 Flash efficiency
• 🔒 100% Local — all data stays on your machine, zero cloud dependency
• ⚡ Zero Config — auto-detects agents from their default log locations
• 🆓 Free & Open Source — MIT licensed, forever free

macOS / Linux:

curl -fsSL https://tokentelemetry.com/install.sh | bash

Windows (PowerShell):

irm https://tokentelemetry.com/install.ps1 | iex

git clone https://github.com/VasiHemanth/tokentelemetry.git
cd tokentelemetry
./start.sh        # macOS/Linux
# start.bat       # Windows
# node bin/cli.js # cross-platform

Then open: http://localhost:3000

Connected agents, recent activity feed, model distribution pie chart, token burn rate.

Per-project heatmap, tool usage breakdown, agent leaderboard, session timeline.

Full waterfall: system prompt → reasoning → tool calls → responses → final output. See exactly what your agent was thinking.

Cumulative token & cost graphs per agent/model over time. Compare efficiency across models.

Captured plan-mode outputs from Claude Code's /plan command and equivalent in other agents.

• Node.js 18+
• Python 3.9+
• git
• Any supported AI coding agent already installed (Claude Code, Gemini CLI, Codex, etc.)

TokenTelemetry stores lightweight state in ~/.tokentelemetry/:

~/.tokentelemetry/
  aliases.json       # Rename/merge project folder paths
  hidden.json        # Hide specific projects from dashboard
  preferences.json   # App preferences (e.g. update check on/off)
  billing.json       # Per-agent billing-mode overrides
  power.json         # Local-model power & electricity settings
  VERSION            # Current version

All hand-editable JSON — no database, no config GUI needed.

Prefer to keep your system drive clear, or isolate dev-tool state on a secondary drive? Point TokenTelemetry's data directory anywhere:

• Launcher flag — start.sh --data-dir /mnt/d/tt-data (or -d). The folder is created on first write.
• Environment — set TOKENTELEMETRY_DATA_DIR=/mnt/d/tt-data before launching. Used verbatim — that exact folder becomes the store (no .tokentelemetry suffix appended). An explicit --data-dir flag wins over it.

Windows cmd.exe tip: If using quotes around the path, avoid a trailing backslash (e.g. --data-dir "D:\tt\") as \" escapes the quote in cmd.exe. Use forward slashes or omit the trailing slash instead.

Everything — aliases, hidden projects, preferences, billing/power overrides, summaries cache, the update-check stamp — moves together, so a single setting relocates all state. The default remains ~/.tokentelemetry/.

TokenTelemetry does not collect or transmit your logs, sessions, tokens, or costs — those never leave your machine. The one outbound call it makes is an optional update check: about once an hour the dashboard fetches the latest version and curated release notes from GitHub, so you know when new features land. It sends no usage data — only a version request, which (like any web request) exposes your IP and the app name to GitHub.

Turn it off either way:

• In the app — Settings → Updates & privacy → toggle off Check for updates.
• Via environment — set TT_NO_UPDATE_CHECK=1 before launching. This wins over the in-app toggle, so admins can enforce it (e.g. in air-gapped or egress-monitored environments).

TokenTelemetry is local-first and binds to 127.0.0.1 by default so that your agent logs, prompts, and costs never leave the machine. Remote access is an opt-in feature with clear security boundaries (loopback is always exempt; non-loopback requests require a token).

Use the built-in flags when you can reach the machine directly (tailnet, LAN, or a VPS with ports open):

./start.sh --host 0.0.0.0 \
  --allowed-origins your-laptop.tailnet.ts.net,192.168.1.42 \
  --port 3000 --api-port 8000

• --host 0.0.0.0 (or a concrete IP) makes the backend listen on all interfaces.
• --allowed-origins configures CORS on the backend and allowed dev origins for Next.js.
• On a non-loopback --host, a random token is auto-generated and printed once (unless you pass --auth-token or --insecure-no-auth).
• The launcher prints a connect URL (http://.../?token=...) and the dashboard shows a "Connect a device" panel with a QR code.
• Your own browser on the server machine (loopback) never needs the token. Remote clients send it as Authorization: Bearer <token> (or ?token=... for images and artifacts).

Security note: Only use --insecure-no-auth on a fully trusted private network. See the warning printed by the launcher and run ./start.sh --help for the full flag reference and examples.

When you load the dashboard from the remote address (e.g. the Network URL printed by Next.js), the frontend automatically derives the backend URL from window.location + the API port, so everything just works.

This pattern is common when your agents (and their logs) run on a remote VPS or server and you only have SSH access, or you prefer to keep the dashboard bound to localhost on the remote side.

On the remote machine (where the agent logs live — this is required because TokenTelemetry reads files locally):

NEXT_PUBLIC_API_BASE=http://localhost:8000 ./start.sh

The NEXT_PUBLIC_API_BASE override tells the frontend to always talk to the backend at that address (instead of deriving it from the browser's window.location). It is inherited by the Next.js dev server.

On your laptop:

ssh -N -L 3000:127.0.0.1:3000 -L 8000:127.0.0.1:8000 user@remote-host

Then open http://localhost:3000 on your laptop.

Both the UI and all data fetches are forwarded over the single SSH connection. The old single-port example (-L 3000:... only) produced a page skeleton with no data because the frontend would try to reach the backend on the laptop's localhost instead of the remote.

This method requires no firewall changes on the remote machine and reuses your existing SSH authentication.

tokentelemetry/
  backend/        FastAPI app (Python) — reads agent logs, serves REST API
  frontend/       Next.js 16 dashboard — React UI
  bin/cli.js      Cross-platform launcher
  install.sh      One-line installer (macOS/Linux)
  install.ps1     One-line installer (Windows)

Q: Does TokenTelemetry send any data to the cloud?
A: No usage data, ever. It reads log files from your filesystem and serves a local web dashboard — your logs, sessions, tokens, and costs never leave your machine. The only outbound call is an optional update check that fetches the latest version and release notes from GitHub (no usage data sent); disable it in Settings → Updates & privacy or with TT_NO_UPDATE_CHECK=1. See Update check.

Q: How does it track Claude Code token usage?
A: Claude Code writes JSONL session logs to ~/.claude/. TokenTelemetry watches those files and parses token counts, tool calls, and reasoning in real time.

Q: Does it work with multiple agents at the same time?
A: Yes. It detects all supported agents and shows them in a unified dashboard. You can filter by agent, model, or project.

Q: Is there a cost to use TokenTelemetry?
A: No. It is free and open-source under the MIT license.

Q: How is TokenTelemetry different from Langfuse, LangSmith, or Helicone?
A: Those tools require you to instrument your code, create an account, and send data to their cloud. TokenTelemetry is 100% local, zero-config, and works by reading the log files your agents already write — no SDK, no API key, no cloud.

Q: Can I monitor Gemini CLI token usage?
A: Yes. TokenTelemetry supports Gemini CLI and shows token counts, costs, and session traces for Google's Gemini models (Gemini 2.0 Flash, Gemini 1.5 Pro, etc.).

Q: Does it support Cursor or GitHub Copilot?
A: Yes. Cursor and GitHub Copilot sessions are detected and tracked.

Q: Is there any other observability tool for Hermes Agent?
A: Not really. Hermes ships its own /usage + /insights and a bundled Langfuse plugin, but no third-party tool treats it as a first-class agent with a dedicated dashboard. Tracking: NousResearch/hermes-agent#6642.

Q: Will it work for my Hermes bot on a VPS?
A: Yes — run TokenTelemetry on the same host (it reads local files). See the Remote Access section above for the two supported methods:

• Direct exposure with --host 0.0.0.0 + token (recommended when the network allows it).
• SSH tunnel with the correct dual-port forward (-L 3000:... -L 8000:...) plus NEXT_PUBLIC_API_BASE on the remote (the previously documented single-port command produced a blank dashboard).

Q: Is "Hermes Agent" the same as the Hermes-3 LLMs?
A: No. Hermes Agent is the open-source agent framework; Hermes-3 is a family of fine-tuned models. TokenTelemetry observes the agent — it can be running any model.

There's no other third-party tool built specifically for Hermes Agent.

Know of another? Open an issue and we'll update this.

• Hermes Agent operators running a Telegram / Discord / cron bot on a VPS — see costs per platform, gateway health, cron-run history, skills + memory state, all in one place
• Individual developers who want to understand how much their AI coding sessions cost
• Teams comparing Claude Code vs Gemini CLI vs Codex efficiency
• Researchers studying LLM agent behavior, tool call patterns, and reasoning chains
• Engineering managers tracking AI tooling ROI across projects
• Prompt engineers optimizing prompts by seeing exact token breakdowns

Port conflicts: Check/kill processes on ports 3000 and 8000.
Python not found: Install Python 3.9+ and ensure it's in your PATH.
No sessions showing: Run an agent (Claude Code, Gemini CLI, etc.) first — TokenTelemetry needs existing log files.
Windows issues: Run PowerShell as Administrator for the installer.

We welcome contributions! See CONTRIBUTING.md for guidelines.

git clone https://github.com/VasiHemanth/tokentelemetry.git
cd tokentelemetry
# Make your changes
git checkout -b feat/your-feature
git commit -m "feat: your feature"
git push origin feat/your-feature
# Open a Pull Request

Want to add support for a new agent? Open an issue with the agent name and log format.

claude-code token usage · gemini cli cost tracking · codex token monitor · AI agent observability · LLM token dashboard · coding agent analytics · local LLM monitoring · token cost calculator · AI coding tool metrics · claude code session viewer · openai codex usage · cursor ide analytics · github copilot usage tracker · LLM observability tool · AI agent telemetry · token usage dashboard open source

MIT © 2024 Hemanth Vasi

Hemanth Vasi
🌐 tokentelemetry.com
🐙 github.com/VasiHemanth
🐦 @VasiHemanth on X
💼 LinkedIn

Have an idea, found a bug, or just want to share how you're using TokenTelemetry? Two ways in:

• 💬 GitHub Discussions — ideas, Q&A, show-and-tell
• 🐛 Issues — bugs and concrete feature requests

There's also a feedback button inside the app (bottom-right of every page).

If you find TokenTelemetry useful, please ⭐ star this repo — it helps others discover it!