{"id":48724488,"url":"https://github.com/sriinnu/tokmeter","last_synced_at":"2026-04-24T07:06:23.111Z","repository":{"id":350094508,"uuid":"1197383974","full_name":"sriinnu/tokmeter","owner":"sriinnu","description":"Tokmeter is a comprehensive observability and cost-tracking tool for AI coding agents, it monitors token consumption across 16+ AI assistants","archived":false,"fork":false,"pushed_at":"2026-04-23T20:53:02.000Z","size":1970,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-23T21:28:58.016Z","etag":null,"topics":["cost-analysis","developer-tools","finops","llms","mcp-server","token-costs","token-tracker"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sriinnu.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-31T14:38:31.000Z","updated_at":"2026-04-23T19:59:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sriinnu/tokmeter","commit_stats":null,"previous_names":["sriinnu/tokmeter"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/sriinnu/tokmeter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sriinnu%2Ftokmeter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sriinnu%2Ftokmeter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sriinnu%2Ftokmeter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sriinnu%2Ftokmeter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sriinnu","download_url":"https://codeload.github.com/sriinnu/tokmeter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sriinnu%2Ftokmeter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32212815,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T03:15:14.334Z","status":"ssl_error","status_checked_at":"2026-04-24T03:15:11.608Z","response_time":64,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cost-analysis","developer-tools","finops","llms","mcp-server","token-costs","token-tracker"],"created_at":"2026-04-11T21:49:39.292Z","updated_at":"2026-04-24T07:06:23.105Z","avatar_url":"https://github.com/sriinnu.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"logo.svg\" alt=\"Tokmeter\" width=\"120\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003etokmeter\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\u003cstrong\u003eToken Usage Tracker for AI Coding Agents\u003c/strong\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@sriinnu/tokmeter-core\"\u003e\u003cimg src=\"https://img.shields.io/badge/npm-@sriinnu/tokmeter--core-39d353?style=flat-square\u0026logo=npm\" alt=\"npm\" /\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/node-%3E%3D18-0e4429?style=flat-square\u0026logo=node.js\" alt=\"node\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/license-MIT-26a641?style=flat-square\" alt=\"license\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/bun-monorepo-39d353?style=flat-square\u0026logo=npm\" alt=\"bun\" /\u003e\n\u003c/p\u003e\n\n---\n\nTokmeter tracks token consumption across **16+ AI coding agents**, breaks it down by **project, model, provider, and day**, and gives you **five surfaces** to explore your data: CLI, TUI, web dashboard, MCP server, and macOS menu bar.\n\nPowered by [`@sriinnu/kosha-discovery`](https://www.npmjs.com/package/@sriinnu/kosha-discovery) for real-time model pricing across 20+ providers including 300+ OpenRouter models.\n\n## Why\n\nAI coding agents burn tokens. Lots of them. Tokmeter answers:\n\n- How much did **this project** cost?\n- Which **model** consumed the most tokens?\n- What's my **daily spend** trend?\n- How do costs break down across **providers**?\n- What's my **cache hit rate** and how much is caching saving me?\n- Which **cheaper model** could I be using instead?\n\nNo social features. No leaderboard. Just your data, locally.\n\n## Quick Start\n\n```bash\n# Run directly\nnpx @sriinnu/tokmeter-cli\n\n# Or install globally\nnpm install -g @sriinnu/tokmeter-cli\ntokmeter\n```\n\n## Packages\n\n| Package | What | Install |\n|---------|------|---------|\n| [`@sriinnu/tokmeter-core`](packages/core/) | Session parsers, aggregator, pricing, public API | `npm install @sriinnu/tokmeter-core` |\n| [`@sriinnu/tokmeter-cli`](packages/cli/) | CLI -- table + JSON output + cost digest | `npx @sriinnu/tokmeter-cli` |\n| [`@sriinnu/tokmeter-tui`](packages/tui/) | Interactive terminal UI with charts | `npx @sriinnu/tokmeter-tui` |\n| [`@sriinnu/tokmeter-web`](packages/web/) | React + Plotly web dashboard with live mode | See [Web App](#web-app) |\n| [`@sriinnu/drishti`](packages/mcp/) | MCP server + live TUI + statusline + daemon | `npx @sriinnu/drishti` |\n\n## Consume Tokmeter From Other Apps\n\nUse the surface that matches the job:\n\n| Need | Use | Notes |\n| --- | --- | --- |\n| Local programmatic access in Node/Bun | `@sriinnu/tokmeter-core` | Lowest-level scan + aggregation + cleanup API |\n| Shell / CI automation | `@sriinnu/tokmeter-cli --json` | Best machine-readable contract for scripts |\n| Convenience helpers without shelling out | `@sriinnu/tokmeter-cli` imports | Exposes summary/project/model/stats helpers plus digest/cleanup/restore entrypoints |\n| Live in-session token/cost answers | `@sriinnu/drishti` | MCP + daemon + statusline + live tracker |\n\n### Programmatic convenience helpers\n\n```ts\nimport {\n  loadTokmeterSummary,\n  loadTokmeterProjects,\n  loadTokmeterModels,\n  loadTokmeterStats,\n  lookupTokmeterPricing,\n} from \"@sriinnu/tokmeter-cli\";\n\nconst summary = await loadTokmeterSummary({ month: true });\nconst projects = await loadTokmeterProjects({ project: \"tokmeter\" });\nconst models = await loadTokmeterModels({ providers: [\"codex\"] });\nconst stats = await loadTokmeterStats({ week: true, light: true });\nconst pricing = await lookupTokmeterPricing(\"claude-sonnet-4-20250514\");\n```\n\n### Stable shell contract\n\n```bash\nnpx @sriinnu/tokmeter-cli --json\nnpx @sriinnu/tokmeter-cli models --json --project tokmeter\nnpx @sriinnu/tokmeter-cli digest --json --period week\n```\n\nFor a deeper integration guide, see [`docs/consuming-tokmeter.md`](docs/consuming-tokmeter.md).\n\n## CLI Usage\n\n```bash\ntokmeter                          # overview (all projects)\ntokmeter models                   # per-model cost breakdown\ntokmeter daily                    # daily usage over time\ntokmeter projects                 # per-project summary\ntokmeter stats                    # overall statistics\ntokmeter pricing sonnet           # lookup model pricing\ntokmeter digest                   # weekly cost digest with optimization score\ntokmeter digest --period today    # today's digest\ntokmeter digest --period month    # monthly digest\n\n# Live \u0026 Daemon\ntokmeter live                     # TUI dashboard\ntokmeter statusline               # Statusline mode\ntokmeter daemon start             # Start aggregation daemon\ntokmeter daemon stop              # Stop daemon\ntokmeter daemon status            # Check daemon status\n\n# Installer (all editors)\ntokmeter install-statusline       # Install statusline for ALL editors\ntokmeter install-mcp              # Install MCP for ALL editors\ntokmeter editors                  # List supported editors\n\n# Filters\ntokmeter --project my-app         # specific project\ntokmeter --claude --opencode      # specific providers\ntokmeter --today                  # today only\ntokmeter --week                   # last 7 days\ntokmeter --month                  # current month\ntokmeter --since 2025-01-01 --until 2025-12-31\n\n# Output\ntokmeter --json                   # JSON output (for piping/CI)\ntokmeter --light                  # skip pricing (faster)\n```\n\n### Cost Digest\n\nThe `digest` command gives you a cost report card:\n\n```\n+==========================================+\n|  Weekly Digest: Mar 30 - Apr 5, 2026     |\n+==========================================+\n\n  Total Spend:     $2,847.32\n  vs Last Week:    $2,102.55 (+35.4%)\n  Daily Average:   $406.76\n  Busiest Day:     Thursday ($892.11)\n\n  Cache Efficiency: 98.2% hit rate\n  Est. Savings:     $977.52\n\n  Optimization Score: B (85/100)\n    Cache:           A (100)\n    Model Selection: A (100)\n    Discipline:      F (40)\n\n  Tips:\n  - You spent $620 on GPT-5.4 today - Sonnet would've cost $124\n  - Cache efficiency is solid at 98% - keep sessions active\n```\n\nAliases: `tokmeter weekly`, `tokmeter report`\n\n### Example Output\n\n```\n+---------------------------+------------+--------+--------+----------+---------+\n| Project                   | Tokens     | Cost   | Models | Providers| Days    |\n+---------------------------+------------+--------+--------+----------+---------+\n| myapp                     | 2.4M       | $24.20 | 3      | 2        | 14      |\n| api-server                | 800.0K     | $8.50  | 2      | 1        | 7       |\n| scripts                   | 120.5K     | $1.44  | 1      | 1        | 3       |\n+---------------------------+------------+--------+--------+----------+---------+\n\nTotal: 3.3M tokens | $34.14 | 24 active days\n```\n\n## Drishti -- MCP Server + Live Observatory + Daemon\n\n[`@sriinnu/drishti`](packages/mcp/) is the observability layer. It provides:\n\n### MCP Server\n\nExposes 20 token usage tools to Claude Code, Codex, Cursor, and any MCP client.\n\n```json\n// ~/.claude/settings.json\n{\n  \"mcpServers\": {\n    \"drishti\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@sriinnu/drishti\", \"mcp\"]\n    }\n  }\n}\n```\n\n**Data Tools:** `token_usage`, `cost_breakdown`, `daily_trend`, `session_cost`, `budget_check`, `compare_models`, `export_csv`\n\n**Cost Intelligence Tools:**\n- `cache_efficiency` -- Cache hit rate, dollar savings, per-model breakdown\n- `model_advisor` -- What-if analysis (Opus vs Sonnet, GPT-5 vs GPT-4o)\n- `budget_alert` -- Proactive budget monitoring with projected spend and alerts\n- `cost_optimization_tips` -- Actionable recommendations based on usage patterns\n\n### Statusline Hook\n\nLive animated status bar inside Claude Code with cache hit rate:\n\n```json\n// ~/.claude/settings.json\n{\n  \"statusLine\": {\n    \"type\": \"command\",\n    \"command\": \"npx -y @sriinnu/drishti statusline\"\n  }\n}\n```\n\n```\n【♾️】 ○ ❯ 📂myproject ❯ 🌿main ❯ ⚡$5.97 ❯ sonnet-4 ❯ ↑42.5K ↓18.2K ❯ ⚡98.2% ❯ 🔥$4.55/hr ❯ 📈 today $37.8\n```\n\nFeatures:\n- Rainbow animated infinity logo\n- Real-time token counts with intensity bars\n- Live cost tracking with hourly burn rate\n- Cache hit rate indicator (green \u003e80%, yellow 50-80%, red \u003c50%)\n- Today's total across all providers\n- Cross-provider aggregation when daemon is running\n- Bulletproof -- 4 concentric safety layers guarantee output even if dependencies fail\n\n### Cross-Provider Aggregation Daemon\n\nThe daemon aggregates token usage across **multiple AI coding assistants running simultaneously**:\n\n```bash\n# Start the daemon\ntokmeter daemon start\n\n# Check status\ntokmeter daemon status\n\n# Stop the daemon\ntokmeter daemon stop\n```\n\nWhen multiple Claude Code, Codex, or OpenCode instances are running, the statusline shows **aggregated totals** across all of them in real-time via WebSocket.\n\n### Live TUI\n\n```bash\nnpx @sriinnu/drishti live\n# or\ntokmeter live\n```\n\nReal-time terminal dashboard with 2-second refresh.\n\n## Universal Installer\n\nInstall statusline and MCP across **all supported editors** at once:\n\n```bash\n# Install statusline for Claude Code, OpenCode, Codex\ntokmeter install-statusline\n\n# Install MCP server for all editors\ntokmeter install-mcp\n\n# List supported editors\ntokmeter editors\n```\n\nSupported editors:\n- **Claude Code** -- statusline + MCP\n- **OpenCode** -- statusline + MCP\n- **Codex** -- statusline + MCP\n- **Cursor** -- MCP\n- **Windsurf** -- MCP\n- **Zed** -- MCP\n\n## TUI\n\nInteractive terminal UI with bar charts, sparklines, and contribution heatmaps.\n\n```bash\nnpx @sriinnu/tokmeter-tui\n```\n\n| View | Key | Description |\n|------|-----|-------------|\n| Overview | `1` | Bar charts, sparklines, provider breakdown |\n| Models | `2` | Sortable table with inline charts |\n| Daily | `3` | Sparkline + heatmap |\n| Stats | `4` | Streaks, averages, contribution calendar |\n\n## Web App\n\nReact + Plotly dashboard with rich visualizations and **live mode**.\n\n```bash\ncd packages/web\nbun install\nbun run dev\n```\n\nOpen http://localhost:3000\n\nWhen the daemon is running, the web dashboard connects via WebSocket and shows **live session data** alongside historical charts:\n- Green pulsing \"Live\" indicator when connected\n- Real-time cost, token counts, and active sessions\n- Per-provider and per-model live breakdowns\n- Falls back to static data when daemon is offline\n\n| Chart | Description |\n|-------|-------------|\n| Model cost bars | Horizontal bar chart comparing model costs |\n| Provider pie | Donut chart of cost split by provider |\n| Daily trend | Dual-axis line chart (tokens + cost) |\n| Token breakdown | Stacked bars (input/output/cache per model) |\n| Contribution heatmap | GitHub-style calendar heatmap |\n\nExport data: `tokmeter --json \u003e packages/web/public/data.json`\n\n## Supported Providers\n\n| Provider | Data Location |\n|----------|--------------|\n| Claude Code | `~/.claude/projects/**/*.jsonl` |\n| OpenCode | `~/.local/share/opencode/opencode.db` (SQLite) + legacy JSON |\n| Codex CLI | `~/.codex/sessions/*.jsonl` |\n| Gemini CLI | `~/.gemini/tmp/*/chats/*.json` |\n| Cursor IDE | `~/.config/tokscale/cursor-cache/` (API sync) |\n| Amp | `~/.local/share/amp/threads/` |\n| Droid | `~/.factory/sessions/` |\n| OpenClaw | `~/.openclaw/agents/` + legacy paths |\n| Pi | `~/.pi/agent/sessions/` |\n| Kimi CLI | `~/.kimi/sessions/` |\n| Qwen CLI | `~/.qwen/projects/` |\n| Roo Code | VS Code globalStorage |\n| Kilo | VS Code globalStorage |\n| Kilo CLI | `~/.local/share/kilo/kilo.db` (SQLite) |\n| Mux | `~/.mux/sessions/` |\n| Synthetic | Re-attributed from other sources |\n\nOpenRouter models (free and paid) are automatically detected via model ID format and priced through kosha-discovery's OpenRouter integration.\n\n## Pricing\n\nPricing is resolved via [`@sriinnu/kosha-discovery`](https://github.com/sriinnu/kosha-discovery):\n\n1. **Static table** -- 50+ models with accurate direct-api rates\n2. **kosha direct** -- authenticated API calls to Anthropic, OpenAI, Google, etc.\n3. **kosha fuzzy** -- 300+ OpenRouter models for the long tail\n4. **Reasoning tokens** -- dedicated rates for o1/o3/gemini-thinking/deepseek-r1\n\nCovers: Anthropic, OpenAI, Google, DeepSeek, xAI (Grok), Mistral, Meta (Llama), Moonshot/Kimi, Cohere, Perplexity, Qwen, and more.\n\nAll formatters are NaN/Infinity-safe -- malformed data never leaks into output.\n\n## Architecture\n\n```\nSession Files (local disk)\n    |\n@sriinnu/tokmeter-core (parsers -\u003e aggregation -\u003e pricing via @sriinnu/kosha-discovery)\n    |\n+----------+----------+----------+----------+-----------+\n|  CLI     |  TUI     |  Web App | Drishti  | Daemon    |\n| (table)  | (Ink)    | (Plotly) | (MCP)    | (WebSocket)|\n| (digest) |          | (live)   | (20 tools)|           |\n+----------+----------+----------+----------+-----------+\n```\n\n## Development\n\n```bash\ngit clone https://github.com/sriinnu/tokmeter.git\ncd tokmeter\nbun install\nbun run build\n\n# Run surfaces\nbun run cli                    # CLI overview\nbun run cli:models             # Model breakdown\nbun run cli:daily              # Daily usage\nbun run cli:projects           # Project breakdown\nbun run cli:stats              # Statistics\nbun run cli:digest             # Cost digest report\nbun run cli:pricing            # Model pricing lookup\nbun run tui                    # Interactive TUI\nbun run dev:web                # Web dashboard (dev server)\nbun run drishti:live           # Live TUI dashboard\nbun run drishti:serve          # MCP server\nbun run drishti:statusline     # Statusline hook\n\n# Daemon\nbun run daemon:start           # Start aggregation daemon\nbun run daemon:stop            # Stop daemon\nbun run daemon:status          # Check daemon status\n\n# Installer\nbun run install:statusline     # Install statusline for all editors\nbun run install:mcp            # Install MCP for all editors\nbun run list:editors           # List supported editors\n\n# macOS menu bar (Swift app)\nbun run bar                    # Build + install to /Applications + launch (ad-hoc signed)\nbun run bar:build              # Build only — produces ./packages/macos-bar/TokmeterBar.app\nbun run bar:signed             # Developer ID signed — Gatekeeper-friendly for AirDrop\nbun run bar:release            # Signed + notarized + stapled + appcast.xml updated\n                               # Requires packages/macos-bar/.env with Apple credentials.\n                               # See packages/macos-bar/RELEASE.md for the full pipeline.\nbun run bar:publish            # Upload the built TokmeterBar-\u003cversion\u003e.zip to a\n                               # GitHub release v\u003cversion\u003e. Run after bar:release.\nbun run bar:ship               # One-shot: clean → bar:release → bar:publish.\n                               # Bump CFBundleShortVersionString in bundle.sh first.\n\n# Cleanup\nbun run clean                  # Remove dist/, *.tsbuildinfo, .build/, *.app, *.zip, *.dSYM,\n                               # plus any leaked tsc emit (.js/.d.ts) inside src/ dirs\n\n# Quality\nbun run test                   # Run tests (30 tests)\nbun run lint                   # Lint\nbun run format                 # Format\n```\n\n## License\n\nMIT (c) Srinivas Pendela\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsriinnu%2Ftokmeter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsriinnu%2Ftokmeter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsriinnu%2Ftokmeter/lists"}