TokenTelemetry：把 coding agent 的 token、成本和工具调用留在本地看
现在用 coding agent 写代码，最难估的不是“它能不能改完”，而是它到底消耗了多少上下文、花了多少钱、调用了哪些工具、在哪一步开始绕路。Claude Code、Codex、Gemini CLI、Cursor、Copilot 各自有日志和计量方式，但日常工作里很少有人愿意为了查一次 session 成本去翻一堆 JSONL、缓存目录和客户端 UI。
今天想记下的 VasiHemanth/tokentelemetry，切的是这个更偏工程管理的痛点。它不是新的 agent runtime，而是一个 100% local 的 observability dashboard：读取本机 agent 已经写下来的日志，把 token usage、LLM cost、tool calls、session traces、reasoning steps、plan capture 和 per-project analytics 放到同一个本地页面里。
按 GitHub repository page、README、Releases page、Tags page、commit history 和 LICENSE 在 2026-07-14 能核验的公开信息，VasiHemanth/tokentelemetry 当前有 229 stars、30 forks。仓库语言占比里 Python 46.7%、TypeScript 44.5%，GitHub 也把 Python 列在语言列表第一位；许可证是 MIT。仓库首个公开 commit 是 3806fc1b，时间为 2026-04-24 06:34:51 UTC；默认分支 main 当前最新提交是 8e074298，提交时间 2026-07-13 15:21:23 UTC。GitHub Releases 和 Tags 页面目前都显示没有发布 release 或 tag。
项目概览
| 属性 | 详情 |
|---|---|
| 仓库 | VasiHemanth/tokentelemetry |
| 定位 | 本地 AI coding / autonomous agent observability dashboard |
| Stars | 229 |
| Forks | 30 |
| 主语言 | Python 46.7%，TypeScript 44.5% |
| 许可证 | MIT |
| 首个公开 commit | 3806fc1b，2026-04-24 06:34:51 UTC |
| 最新 main 提交 | 8e074298，2026-07-13 15:21:23 UTC |
| Latest GitHub release | 无公开 release |
| 最新 tag | 无公开 tag |
| 核心入口 | curl -fsSL https://tokentelemetry.com/install.sh | bash、./start.sh、node bin/cli.js |
| 关键词 | local-first、token usage、cost tracking、session trace、tool calls、Codex、Claude Code、Hermes Agent |
它解决的是 agent 账单和行为黑箱
TokenTelemetry 的 README 里把问题说得很直接：agent 很强，但 token 消耗很快；你需要知道一次 refactor 花了多少 token，哪个 model 更省，agent 实际调用了什么工具，是否按计划在走。
这类问题过去常被当成“事后账单”处理。等 API bill 出来，或者某个 session 明显跑飞了，再回头翻日志。但 coding agent 进入日常开发后，这种方式太迟。一个大重构、一次跨仓库搜索、几轮失败测试，很容易在不知不觉中烧掉很多上下文和 API cost。
TokenTelemetry 的切入点是 read-only：不要求你在应用代码里接 SDK，也不要求把 agent traffic 代理到云端。它读取 Claude Code、Codex CLI、Gemini CLI、Cursor、GitHub Copilot、OpenCode、Qwen、Vibe、Antigravity、Grok Build 以及 Hermes Agent 等工具的本地 session 日志，然后在本机 dashboard 里做统一视图。
这个方向实用的地方，是它承认 agent observability 首先应该贴近开发者机器。对很多团队来说，最初需要的不是一套完整 APM，而是能回答三个问题：哪个项目在烧 token，哪个 agent session 异常长，最近失败的工作流到底调用过什么工具。
本地优先，但不是“完全无网络”
README 很强调 no signup、no cloud、logs never leave your machine。对 agent 日志来说，这个承诺重要，因为 session trace 可能包含 prompt、文件路径、命令输出、项目名，甚至部分代码片段。把这些东西默认送到外部服务，很难在公司环境里通过审查。
不过它也不是完全没有网络行为。README 的 privacy section 写得比较明确：dashboard 会定期向 GitHub 做 update check；另外还有默认开启、可关闭的匿名产品使用 telemetry，发送的是页面访问、功能使用、系统架构、近似国家、检测到的 agent 名称等内容，不包含代码、prompt、model output、路径、项目名、token counts 或 costs。
这个细节值得写进采用判断里。TokenTelemetry 的核心数据面是本地的，但团队如果对任何 outbound signal 都敏感，还是应该先进入 Settings 关闭 usage telemetry，或者在隔离环境里验证网络行为。
对 Codex / Claude Code 用户最直接的价值
日常用 Codex 或 Claude Code 时，真正烦人的不是“有没有日志”，而是日志太分散、太低层。一个 session 里可能有 plan、tool calls、失败命令、重试、缓存命中、子任务和多轮模型输出。开发者通常只看到最后的 diff 或回答，很少回看过程。
TokenTelemetry 把这些过程变成几个更适合扫读的维度：per-session cost、per-project heatmap、tool usage breakdown、agent leaderboard、model analytics、budget alerts、session waterfall、plan capture。它不是为了替代 agent UI，而是为了在 agent 工作之后留下可比较、可追踪的运行账本。
我尤其看重 tool call analytics 和 session trace。coding agent 的失败很多不是模型完全不会，而是工具选择、上下文刷新、测试命令、文件定位这些步骤出错。能看到“它在哪一步调用了什么工具、失败率如何、哪个项目最常触发长 session”，比单纯知道总 token 数更有价值。
Hermes Agent 支持让它不只服务 coding agent
README 近期重点强调了 Hermes Agent dashboard。Hermes Agent 不只是 CLI coding agent，它可能跑在 Telegram、Discord、Slack、Feishu、cron、webhook 等入口后面。TokenTelemetry 为它单独做了 /hermes 视图，读取 $HERMES_HOME 或 ~/.hermes/，展示 source platform、API call latency、cache hit、subagent cards、skills、memory、cron health、gateway health 和 cost anomaly detection。
这说明项目的野心不止是“给 Claude Code 做个图表”。它更像是在把多入口 agent 的运行轨迹统一成一个本地控制台。对于已经把 agent 放进定时任务、聊天入口或内部工具的团队，这个方向会比普通 token counter 更有用。
当然，这也带来复杂度。支持的 agent 越多，日志格式变化、版本兼容、路径发现、价格表同步都会变成维护压力。当前仓库提交很活跃，但项目仍然很年轻，最好先把它当成观察和诊断工具，而不是唯一账务来源。
适合什么场景
第一类场景，是你已经同时使用多个 coding agent，并且想知道它们在不同项目上的真实 token burn、成本和工具调用差异。
第二类场景，是团队需要给 agent 使用设预算提醒，但又不想让预算系统直接阻断工作流。TokenTelemetry 的 budgets and alerts 是观察型的：提醒你接近阈值，但不替你拦截 agent。
第三类场景，是你想复盘某次 agent session：它是否按 plan 走，调用了哪些工具，哪个命令失败，为什么最后变成了长时间循环。
第四类场景，是本地或半本地的 autonomous agent。Hermes Agent 支持说明它可以看更长生命周期的 agent，而不只是一次 CLI 对话。
需要注意的地方
第一，项目没有正式 GitHub release 或 tag。安装路径虽然简单，但生产团队最好 pin commit，或者至少在升级前检查 UPDATE.json、changelog 和实际 diff。
第二，它读取多个 agent 的本地日志目录，这意味着权限面比普通 dashboard 更敏感。即使它声明 read-only，也应该在自己的机器上确认它访问哪些目录、保存哪些 cache、是否符合团队的安全要求。
第三，README 中有一些“支持多个 agent / 价格模型 / reasoning trace”的能力描述很诱人，但不同 agent 的日志质量和稳定性并不一样。真实效果要按自己使用的客户端逐个验证。
第四，默认匿名 usage telemetry 可关闭，但不是默认关闭。如果你写在公司环境推荐清单里，这一点需要明确标注。
小结
TokenTelemetry 抓到的是 AI coding 工作流里越来越具体的问题：我们不只需要 agent 产出代码，也需要知道它怎么工作、花了多少、哪里绕路、哪个项目最容易烧上下文。
如果你已经把 Codex、Claude Code、Cursor、Gemini CLI 或 Copilot 当成日常工具，但对 token 成本和 session 行为基本靠感觉判断，VasiHemanth/tokentelemetry 值得试。它还年轻，也还没有正式 release；但本地优先、read-only、跨 agent 的 observability 方向，是 AI 开发工具链里会越来越需要的一层。