Summary

TokenTelemetry is a free, open-source, 100% local observability dashboard designed for AI coding and autonomous agents. It addresses the challenge of understanding token consumption, LLM costs, tool usage, and reasoning across diverse AI agents like Claude Code, Gemini CLI, and Hermes Agent. By providing a unified, privacy-preserving view directly on the user's machine, it empowers developers and researchers to efficiently monitor and optimize their AI agent workflows without external dependencies or data sharing.

How It Works

The core approach involves automatically detecting and parsing log files generated by supported AI agents from their default locations. A local backend, built with FastAPI (Python), processes these logs, while a Next.js/React frontend visualizes the telemetry data. This architecture enables a zero-configuration setup, eliminating the need for code instrumentation, SDKs, or API keys. The primary advantage is complete data privacy, as all AI usage logs, sessions, tokens, and costs remain exclusively on the user's machine.

Quick Start & Requirements

• Primary Install:
  • 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
  • Alternatively, clone the repository and run ./start.sh (or start.bat on Windows) from the project directory.
• Prerequisites: Node.js 18+, Python 3.9+, Git. Requires at least one supported AI coding agent to be installed and operational.
• Links:
  • Website & Docs: https://tokentelemetry.com
  • GitHub Repository: https://github.com/VasiHemanth/tokentelemetry

Highlighted Details

• Hermes Agent Observability: Features a dedicated dashboard (/hermes) for autonomous agents, supporting 38 platforms (CLI, Telegram, Discord, cron, webhook, etc.) and providing insights into gateway health, cron jobs, skills, and memory.
• Comprehensive Telemetry: Tracks real-time token usage, LLM costs per session/project/agent, detailed session traces (waterfall view), tool call analytics, and plan capture.
• Model Efficiency Analytics: Enables direct comparison of token efficiency and cost across different LLMs (e.g., GPT-5.4 vs. Claude 4.6 Sonnet vs. Gemini 3.1 Flash).
• Local-First Privacy: Guarantees that all AI usage data, including logs, prompts, and costs, never leaves the user's machine. Optional anonymous product-usage telemetry can be disabled.
• Zero Configuration: Automatically detects and integrates with supported agents without manual setup or configuration files.

Maintenance & Community

The project is maintained by Hemanth Vasi. Community engagement is facilitated through GitHub Discussions for general inquiries and ideas, and GitHub Issues for bug reports and feature requests.

Licensing & Compatibility

• License: MIT License.
• Compatibility: The MIT license permits commercial use and integration with closed-source projects. The tool's local-first, log-parsing approach minimizes external compatibility concerns.

Limitations & Caveats

TokenTelemetry's functionality is limited to the explicitly supported list of AI agents; integration with new agents requires manual effort or feature requests. While designed for local use, enabling remote access necessitates specific configuration steps (e.g., SSH tunneling or port exposure with authentication), adding complexity. The application does not provide a global command-line interface and must be launched from its cloned repository directory. Optional outbound calls for update checks and anonymous telemetry are present but configurable.