TokenTracker tackles a problem that’s becoming more common as developers juggle multiple AI coding assistants: how do you accurately track token usage and costs across various tools without slowing them down or compromising privacy?
what tokentracker does and how it works
TokenTracker is a local-first command-line tool written in JavaScript for Node.js 20+ that aggregates token usage data and cost estimates from 13 different AI coding agents including Claude Code, Codex, Cursor, Gemini, Kiro, OpenCode, OpenClaw, Every Code, Hermes, GitHub Copilot, Kimi Code, CodeBuddy, and oh-my-pi.
Instead of wrapping or proxying each AI CLI — which can introduce latency or complexity — TokenTracker uses a clever hook-based architecture. It writes SessionEnd hooks or TOML notify entries directly into each tool’s native config files (like settings.json or config.toml). This means each AI tool notifies TokenTracker when a session finishes without any runtime overhead or intrusive instrumentation.
Additionally, TokenTracker passively reads telemetry outputs from SQLite, JSONL, and OpenTelemetry (OTEL) logs where available, giving it broad coverage without performance penalties.
All collected data is parsed and aggregated into 30-minute UTC buckets, normalizing usage across tools with different logging formats and session timings. This aggregated data is stored in a local SQLite database.
The repo also serves a web dashboard on localhost:7680 where users can view detailed usage trends, model breakdowns, and cost analysis. This dashboard runs locally and requires no network connectivity, supporting privacy by design.
Beyond telemetry, TokenTracker includes a skills manager syncing over 250 public skills across multiple agents, and a cost engine pricing more than 2,200 models using LiteLLM data. Optional macOS-specific features include a menu bar app with desktop widgets and a WKWebView-based dashboard.
the architecture and technical strengths behind tokentracker
What distinguishes TokenTracker is its zero-overhead integration pattern. Writing hooks directly into each AI CLI’s config means it never proxies or intercepts API calls or CLI commands. This avoids the common tradeoff where telemetry tools add latency or complexity in the request path.
The 30-minute UTC bucketing strategy is a practical design choice for normalizing data from disparate sources. AI tools log sessions differently — some write JSONL transcripts, others update SQLite databases, and some emit OTEL traces. TokenTracker’s parsers unify these into consistent time-based buckets for easier analysis.
The local SQLite database provides a lightweight, reliable store that’s easy to query for the dashboard and offline use. It also keeps all telemetry data private, collecting only token counts and timestamps — no prompt or response content is stored.
The skills manager is an interesting add-on, allowing users to browse and sync hundreds of public skills across supported agents. This indicates the tool is designed not just for passive tracking but also for active management of AI coding workflows.
The codebase is JavaScript-based, targeting Node.js 20+, which is modern but means users need to be comfortable with that environment. The macOS menu bar app and widgets are a nice touch for desktop users but limit platform parity.
Tradeoffs include the macOS-only limitation on some components and the complexity of supporting many heterogeneous AI tools with different telemetry mechanisms. The repo’s approach balances coverage with minimal impact on the AI CLIs themselves.
quick start with tokentracker
Getting started with TokenTracker is straightforward if you have Node.js 20+ installed. The CLI runs on macOS, Linux, and Windows, while some features like the menu bar app and Cursor SQLite reader are macOS-only.
Here’s the quick start from the README:
npx tokentracker-cli
That single command installs hooks, syncs data, and opens the dashboard at http://localhost:7680.
You get:
- A local dashboard showing usage trends, model breakdowns, and cost analysis
- Auto-detected hooks for every supported AI tool you have installed
- A skills manager syncing 250+ public skills across Claude, Codex, Gemini, OpenCode, Hermes
- Fully local operation with no accounts or API keys required (except optional leaderboard)
For macOS users wanting a native experience, there’s a menu bar app available as a .dmg file, featuring desktop widgets and a menu bar status icon.
TokenTracker can also be installed globally for easier CLI access:
npm i -g tokentracker-cli
tokentracker # Open the dashboard
tokentracker sync # Manual sync
tokentracker status # Check hook status
tokentracker doctor # Health check
Homebrew installation is supported on macOS as well.
verdict: who should consider tokentracker?
TokenTracker is a solid choice for developers or teams who regularly use multiple AI coding assistants and want a unified, privacy-respecting way to track token usage and costs. Its local-first, hook-based design avoids the runtime overhead and complexity of proxy or wrapper approaches.
That said, it requires some setup and comfort with Node.js 20+, and macOS users get the fullest feature set with the menu bar app and widgets. The tool doesn’t collect prompts or responses, which is great for privacy but limits deeper analytics.
If you’re juggling AI coding tools and want transparent expense tracking without sacrificing performance or privacy, TokenTracker is worth exploring. Its architecture is clever, its data normalization pragmatic, and it’s one of the few tools aiming to unify telemetry across a broad and growing range of AI coding agents.
Related Articles
- OpenAI Codex CLI: local-first AI coding assistant with ChatGPT integration — OpenAI Codex CLI brings AI coding assistance local to your terminal, integrating with ChatGPT plans for powerful hybrid
- CC Switch: unified management for AI coding CLIs in a cross-platform Rust desktop app — CC Switch is a Rust-based cross-platform desktop app that centralizes management of AI coding CLIs like Claude Code and
- Beads: a distributed graph issue tracker for multi-agent AI workflows — Beads is a Go-based CLI tool that uses Dolt-backed version control to manage AI agent tasks as a dependency-aware graph,
- Inside Google Gemini CLI: a terminal-first AI agent with extensible Model Context Protocol — Google Gemini CLI is a TypeScript-based terminal AI agent offering direct Gemini model access, extensibility via MCP, an
→ GitHub Repo: mm7894215/TokenTracker ⭐ 378 · JavaScript