Local observability for AI coding agents and autonomous agents — Claude Code, Codex, Gemini CLI, Cursor, Copilot, Qwen, OpenCode, Vibe, Antigravity, Grok Build, Cline, SmallCode, Pi, Muse Code, Prime Agent, and Nous Research's Hermes Agent.
$ npx -y skills add VasiHemanth/tokentelemetry --agent claude-code
Run the curl in your terminal, the rest in Claude Code.
Repo: VasiHemanth/tokentelemetry
What's inside
Local observability for AI coding agents and autonomous agents — Claude Code, Codex, Gemini CLI, Cursor, Copilot, Qwen, OpenCode, Vibe, Antigravity, Grok Build, Cline, SmallCode, Pi, Muse Code, Prime Agent, 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. Your logs never leave your machine.
🌐 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.
| Problem | TokenTelemetry Solution |
|---|---|
| "How much did that Claude Code session cost?" | Real-time cost tracking per session/project |
| "What tools did my agent call?" | Full waterfall trace of every tool call |
| "Which model is most token-efficient for my codebase?" | Per-model analytics & comparisons |
| "Did my agent follow its plan?" | Plan-mode capture & display |
| "I use 3 different agents — unified view?" | Multi-agent dashboard in one place |
TokenTelemetry reads session logs from these agents automatically.
| Agent | Status |
|---|---|
| Claude Code (Anthropic) | ✅ Fully supported |
| Gemini CLI (Google) | ✅ Fully supported |
| OpenAI Codex CLI | ✅ Fully supported |
| Cursor | ✅ Fully supported |
| GitHub Copilot | ✅ Fully supported |
| OpenCode | ✅ Fully supported |
| Qwen | ✅ Fully supported |
| Vibe | ✅ Fully supported |
| Antigravity | ✅ Fully supported |
| Grok Build (xAI) | ✅ Fully supported |
| Cline | ✅ Fully supported |
| SmallCode | ✅ Fully supported |
| Pi Coding Agent | ✅ Fully supported |
| Muse Code (Meta) | ✅ Fully supported |
| Prime Agent | ✅ Fully supported |
| Agent | Status |
|---|---|
| Hermes Agent (Nous Research) | ✅ Fully supported with a dedicated dashboard |
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:
sessions.sourceagent.logdelegate_task subagent cards with summary, tokens, durationRun TokenTelemetry on the same host as Hermes — we read $HERMES_HOME (or ~/.hermes/ if unset) locally, no remote-DB mode yet.
:9119 → :3000)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 (38 source platforms, gateway health, cron jobs, skills, memory, subagent cards — see the section above)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. Activity split across git worktrees rolls up under its parent repo.
Set a spend or token limit on any project — monthly, weekly, or rolling 30-day, overall and per agent. Budgets are observational: TokenTelemetry tracks this period's spend against your limit but never blocks an agent. Set one on the project's Config tab (dollars or tokens, a period, and alert thresholds — 80% and 100% by default). The project header and Insights tab show how close you are, colour-coded as spend climbs, and when spend crosses a threshold an alert lands in the notification center — the bell at the bottom of the sidebar.
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.
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:
start.sh --data-dir /mnt/d/tt-data (or -d). The folder
is created on first write.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 incmd.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/.
Your AI-usage data — logs, sessions, tokens, costs, prompts, file paths, and project names — never leaves your machine. TokenTelemetry makes two optional outbound calls:
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. Only a version request; your IP and app name reach GitHub like any web request.
Anonymous product-usage telemetry (on by default, one-click off) — content-free usage signals sent to a Cloudflare Worker: which pages you open, which features you use, summary success/engine, OS + CPU arch + app version, approximate country (derived at Cloudflare's edge — never your IP), which AI agents are detected (generic names), and a random per-launch session id that is not linked across launches. It never collects your code, prompts, model output, file/directory paths, project names, token counts, costs, IP address, or any stable user or device identifier. Full details: tokentelemetry.com/privacy and Settings → Usage & privacy in the app.
Turning off telemetry:
DO_NOT_TRACK=1 or TT_NO_TELEMETRY=1 (hard off;
useful for enterprise or egress-restricted environments). Auto-disabled in
CI / non-interactive sessions.Turning off the update check:
TT_NO_UPDATE_CHECK=1 (wins over the in-app toggle).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.--host, a random token is auto-generated and printed once (unless you pass --auth-token or --insecure-no-auth).http://.../?token=...) and the dashboard shows a "Connect a device" panel with a QR code.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: Your AI-usage data — logs, sessions, tokens, costs, prompts — never leaves your machine. There are two optional outbound calls: (1) an update check that fetches the latest version from GitHub (no usage data), and (2) anonymous product-usage telemetry (on by default) that sends content-free signals — pages visited, features used, OS/arch/version, approximate country, detected agent names — but never your code, prompts, costs, paths, or any stable identifier. Turn off telemetry in Settings → Usage & privacy or set DO_NOT_TRACK=1 / TT_NO_TELEMETRY=1. Turn off the update check in Settings → Updates & privacy or set TT_NO_UPDATE_CHECK=1. See Privacy & outbound calls.
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:
--host 0.0.0.0 + token (recommended when the network allows it).-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.
| Feature | TokenTelemetry | Langfuse | LangSmith | Helicone |
|---|---|---|---|---|
| 100% Local | ✅ | ❌ | ❌ | ❌ |
| Zero config | ✅ | ❌ | ❌ | ❌ |
| No signup | ✅ | ❌ | ❌ | ❌ |
| Claude Code support | ✅ | Manual | Manual | Manual |
| Gemini CLI support | ✅ | Manual | Manual | ❌ |
| Codex CLI support | ✅ | Manual | Manual | Manual |
| Free | ✅ | Freemium | Freemium | Freemium |
| Open Source | ✅ | ✅ | ❌ | ❌ |
There's no other third-party tool built specifically for Hermes Agent.
| Option | Hermes-aware? | Local? | Dedicated UI? |
|---|---|---|---|
Hermes's own /usage + /insights | ✅ | ✅ | Aggregates only |
| Bundled Langfuse plugin | ❌ generic | Either | Langfuse-shaped |
Manual state.db / agent.log parsing | DIY | ✅ | Build it yourself |
| Langfuse / LangSmith / Helicone | ❌ generic | ❌ | LLM-shaped |
| TokenTelemetry | ✅ | ✅ | /hermes dashboard |
Know of another? Open an issue and we'll update this.
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:
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!
.claude/
agents/
audit-deep.md
audit-scanner.md
audit-verifier.md
CLAUDE.md
hooks/
enforce-update-json.py
prepush-claude-review.py
protect-sensitive-files.py
settings.json
skills/
bug-audit/
SKILL.md
issue-brief/
SKILL.md
.github/
dependabot.yml
FUNDING.yml
ISSUE_TEMPLATE/
bug_report.md
feature_request.md
pull_request_template.md
workflows/
container-publish.yml
deploy-website.yml
pricing-sync.yml
security-audit.yml
sync-traffic.yml
.gitignore
.muse/
MUSE.md
settings.json
AGENTS.md
backend/
.dockerignore
agent_retention.py
billing_mode.py
billing_route.py
codex_goals.py
Dockerfile
harness_config.py
hermes_telemetry.py
history_store.py
insights.py
main.py
notifications.py
power_config.py
power_meter.py
pricing_data.json
pricing_sync.py
pricing.py
requirements.lock
requirements.txt
scan_cache.py
summaries.py
summarizers/
__init__.py
antigravity.py
base.py
claude.py
codex.py
errors.py
gemini.py
ollama.py
openai_compat.py
qwen.py
telemetry.py
test_agent_retention.py
test_antigravity_cli.py
test_billing_mode.py
test_billing_route.py
test_cline_smallcode.py
test_co2.py
test_codex_trace.py
test_copilot_cli_metrics.py
test_copilot_vscode_scan.py
test_delegation.py
test_goals.py
test_hermes_profiles.py
test_hermes_sessions_api.py
test_hermes_telemetry.py
test_history_store.py
test_insights.py
test_local_power.py
test_loops.py
test_muse_prime.py
test_opencode_paths.py
test_pi_scan.py
test_power_config.py
test_power_meter.py
test_pricing_data.py
test_pricing.py
test_prompt_preview.py
test_published_artifacts.py
test_remote_auth.py
test_telemetry_redaction.py
test_tt_paths.py
test_update_check.py
tt_paths.py
bin/
cli.js
CHANGELOG.md
CITATION.cff
CODE_OF_CONDUCT.md
compose.yml
CONTRIBUTING.md
DESIGN.md
docker-compose.prod.yml
docs/
adr/
0000-template.md
0001-record-architecture-decisions.md
0002-durable-history-rollup.md
0003-docs-site-fumadocs.md
README.md
design/
documentation-site.md
durable-history.md
goal-telemetry.md
product-telemetry.md
README.md
frontend/
.dockerignore
.gitignore
AGENTS.md
CLAUDE.md
Dockerfile
eslint.config.mjs
next.config.ts
package-lock.json
package.json
postcss.config.mjs
public/
file.svg
globe.svg
next.svg
vercel.svg
window.svg
README.md
src/
app/
analytics/
page.tsx
globals.css
hermes/
gateway/
page.tsx
kanban/
page.tsx
memory/
page.tsx
page.tsx
profiles/
page.tsx
schedules/
page.tsx
sessions/
page.tsx
skills/
page.tsx
soul/
page.tsx
tools/
page.tsx
icon.svg
layout.tsx
local-models/
page.tsx
page.tsx
projects/
[path]/
_lib/
goals.ts
loops.ts
project-context.tsx
activity/
page.tsx
artifacts/
page.tsx
config/
page.tsx
insights/
page.tsx
layout.tsx
page.tsx
plans/
page.tsx
page.tsx
sessions/
[id]/
page.tsx
settings/
page.tsx
components/
AntigravitySourceBadge.tsx
budgets/
BudgetCard.tsx
BudgetEditor.tsx
ConnectDevice.tsx
CopilotSourceBadge.tsx
feedback/
BrandIcons.tsx
FeedbackFloatingButton.tsx
FeedbackMenu.tsx
links.ts
hermes/
HermesSessionExplorer.tsx
icons/
AgentLogo.tsx
GrokIcon.tsx
HermesIcon.tsx
MuseIcon.tsx
PiIcon.tsx
PrimeIcon.tsx
insights/
LocalPowerInsights.tsx
LayoutWrapper.tsx
Navigation.tsx
notifications/
NotificationBell.tsx
NotificationProvider.tsx
NotificationToaster.tsx
schedules/
CreateScheduleModal.tsx
settings/
AgentFeatureFlags.tsx
BillingSettings.tsx
DrainOrder.tsx
PowerSettings.tsx
RetentionSettings.tsx
UsagePrivacySettings.tsx
SourceBadge.tsx
summarizer/
BackendPicker.tsx
OnboardingModal.tsx
SummarizeRecentButton.tsx
SummaryPanel.tsx
TelemetryNotice.tsx
ThemeProvider.tsx
ThemeToggle.tsx
TokenGate.tsx
ui/
Badge.tsx
Button.tsx
Card.tsx
EmptyState.tsx
index.ts
PageHeader.tsx
Section.tsx
Skeleton.tsx
StatTile.tsx
Table.tsx
WhatsChangedDrawer.tsx
WhatsNewBanner.tsx
lib/
agents.ts
api.ts
billing.ts
budgets.ts
cn.ts
format.ts
hermesCron.ts
hermesSessions.ts
hermesTelemetry.ts
insights.ts
navigation.test.ts
navigation.ts
notifications.ts
pageState.ts
paths.test.ts
paths.ts
power.ts
profileColor.ts
reasoning.test.ts
reasoning.ts
retention.ts
summarizer.ts
telemetry.ts
useScrollState.ts
useSessionState.ts
version.ts
tsconfig.json
install.ps1
install.sh
LICENSE
llms.txt
Makefile
package-lock.json
package.json
plugin/
hermes-dashboard/
dist/
index.js
style.css
manifest.json
README.md
proxy/
cloudflare/
cloudflare-worker.js
.gitignore
package.json
src/
index.js
wrangler.jsonc
README.md
README.md
scripts/
install-hermes-plugin.sh
publish-plugin-template/
.gitignore
LICENSE
plugin.yaml
README.md
publish-plugin.sh
sync_github_traffic.py
start.bat
start.sh
UPDATE.json
website/
.gitignore
content/
docs/
configuration/
billing.mdx
configure-summarizer.mdx
data-directory.mdx
local-models.mdx
meta.json
ports-networking.mdx
privacy.mdx
remote-access.mdx
retention.mdx
docker.mdx
features/
analytics.mdx
artifacts.mdx
automation.mdx
budgets.mdx
dashboard.mdx
hermes.mdx
meta.json
projects.mdx
summarization.mdx
traces.mdx
index.mdx
installation.mdx
meta.json
quick-start.mdx
reference/
cli.mdx
faq.mdx
meta.json
troubleshooting.mdx
supported-agents.mdx
resources.json
mdx-components.tsx
next-env.d.ts
next.config.ts
package-lock.json
package.json
postcss.config.mjs
public/
.nojekyll
apple-icon.png
CNAME
favicon.ico
icon-192.png
icon-512.png
install.ps1
install.sh
llms.txt
manifest.webmanifest
screenshots/
agent-history-retention.png
analytics-delegation.png
analytics-overview.png
analytics.png
artifacts-antigravity.png
artifacts-claude.png
artifacts.png
budget-alerts.png
budget-set.png
budget-usage.png
cost.png
dashboard-hero.png
dashboard.png
hermes.png
loops-goals-config.png
privacy-settings.png
projects.png
summarizer-backend.png
trace-delegated-work.png
trace-workflow-subagents.png
traces.png
scripts/
post-build.mjs
source.config.ts
src/
app/
... 54 moreWant Claude Code, Codex, or Cursor to drive Grok Build? If you already pay for a Grok subscription, this gives any of those agents live X search and data right in their context. A couple of ways to wire it up.
@vasihemanthFAQ
tokentelemetry is a Claude Code plugin with 2 hand-picked skills for development work, indexed on Flowy. Install it with the command on its page. It includes bug-audit, issue-brief. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.