token-monitor
Javis603/token-monitor加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
Token Monitor 是一款专为 AI 编码助手设计的实时 Token 消耗监控工具。作者 Javis 用它管理着自己多台机器上的 Claude Code、Codex、Cursor 等工具——一个人，三台电脑，无数个 AI 对话 Session，传统方式根本记不住花了多少钱。直到他决定：不如自己动手，做一个实时显示的桌面小部件。
这个项目就是 Token Monitor 的起源：一个 Electron 桌面组件，像系统通知栏里的电量指示一样，随时告诉你当前这轮 AI 对话用了多少 Token、花了多少钱、各平台的 API 限额还剩多少。更重要的是——它支持多设备同步，你在笔记本上开的 Claude Code 会话，桌上的台式机也能实时看到消耗数据。
图1：Token Monitor 主界面 logo
随着 Claude Code、GitHub Copilot、Cursor 等 AI 编程工具的普及，开发者面临一个前所未有的问题：Token 是看不见摸不着的。一个 Prompt 下去，扣了多少钱？本月还剩多少 API 限额？Session 之间消耗是否重复计算？这些信息散落在各个平台的后台里，查一次要跳好几次网页，等页面加载完早忘了自己要干什么。
Token Monitor 的核心价值，就是把这个看不见变成随时看。它不是一个网页版的统计面板，而是一个常驻系统托盘的小组件（Windows/macOS/iOS 均支持），数据随取随用，不需要打开任何浏览器标签页。
作者 Javis 的开发动机非常接地气：他同时用 Claude Code 和 Codex，两套工具分别跑在不同的机器上，加上偶尔还要测试 Hermes Agent 和 OpenClaw，传统的做法是每个平台都开一个后台管理页面的标签页。结果往往是：打开了一堆 Tab，问题还没解决，信用卡账单先来了。Token Monitor 解决的就是这个效率问题。
Token Monitor 目前支持 17 种 AI 编程工具，是同类项目中覆盖面最广的：
| 工具 | Token 用量 | API 限额 | Session 详情 |
|---|---|---|---|
 Claude Code | 有 | 有 | 有 |
 Codex | 有 | 有 | 有 |
| Hermes Agent | 有 | - | - |
 OpenCode | 有 | 有 | 有 |
 OpenClaw | 有 | - | - |
 Cursor | 有 | 有 | - |
 Antigravity | 有 | 有 | - |
 Cline | 有 | - | - |
 Kimi CLI | 有 | - | - |
 Qwen CLI | 有 | - | - |
 GitHub Copilot | 有 | 有 | - |
这个矩阵的设计逻辑非常务实：Token 用量是所有工具的共同需求，优先级最高；API 限额次之，需要各平台有对应的 API 接口；Session 详情则需要解析各工具私有的会话文件格式，复杂度最高，只在 Claude Code、Codex、OpenCode 等少数几个工具上实现了。
值得注意的是 Hermes Agent 也在支持列表中，它通过读取 $HERMES_HOME/state.db 获取 Token 数据，展示了跨工具数据互通的可行性。
Token Monitor 的数据采集分为两种模式：
Widget 模式（桌面 GUI）：Electron 应用直接读取本地的会话文件目录，如 ~/.claude/projects/、~/.codex/sessions/、~/.openclaw/agents/ 等，配合文件监听器（基于 chokidar）实现实时增量更新。每次文件变化，Widget 自动刷新显示，无需用户手动操作。
Agent 模式（无头 Headless）：适合服务器和 Linux 环境，通过 node src/agent/agent.js 启动，定期采集数据并推送到 Hub 服务器，不依赖图形界面。开发者可以在没有显示器的远程服务器上运行 AI 编程工具，同时用 Token Monitor 的 Hub 服务聚合多台机器的数据。
两种模式共享同一套数据采集核心模块（src/shared/collector.js，43KB），底层依赖一个专门的工具库 tokscale（@tokscale/cli）来执行实际的 token 解析和成本计算。tokscale 由同一个作者维护，提供了跨平台、跨工具的统一 token 计量能力，是 Token Monitor 的技术基石。
Token Monitor 支持通过 Hub 服务器实现多设备数据聚合。有三种部署方式：
npm run hub，其他设备连接到该机器的 IP:17321，数据通过 SSE（Server-Sent Events）实时推送worker/ 目录部署到 Cloudflare Workers，使用 Durable Objects 实现状态持久化，支持任意网络环境的多设备同步Hub 的设计强调安全：未设置 TOKEN_MONITOR_SECRET 时，Hub 强制绑定到 127.0.0.1，即使暴露到局域网也不会泄露账户身份；设置 Secret 后才允许非本地绑定和跨设备认证。这种渐进式安全模型值得借鉴——开箱即用的默认配置是安全的，高级功能需要显式授权。
除了原始 Token 数量，Token Monitor 还集成了实时汇率转换和自定义定价功能。支持 10+ 种法定货币（CNY、USD、EUR 等），汇率数据来自公开的汇率 API（可配置缓存策略）。用户还可以在 .env 中设置 TOKSCALE_API_KEY 接入 tokScale 平台获取精确的模型定价，或在本地配置自定义定价表，覆盖企业内部使用的私有模型定价。
token-monitor/
src/
electron/ # Electron 主进程 + 渲染进程
main.js # 主入口（126KB，核心业务逻辑）
renderer/ # GUI 组件、显示偏好、视图配置
agent/ # Headless Agent 模式（CLI）
agent.js
hub/ # Hub 服务器（HTTP + SSE）
server.js
shared/ # 核心共享模块（32个文件，600+KB）
collector.js # 数据采集核心（43KB）
usage.js # 用量聚合统计（39KB）
limitCollector.js # API 限额采集（90KB，最大模块）
grokLimits.js # Grok 限额（22KB）
kiroLimits.js # Kiro 限额（15KB）
... # 其他 25 个专项模块
worker/ # Cloudflare Worker（Hub 云端部署）
site/ # 文档网站（静态 HTML）
tests/ # 完整测试套件（Node.js test runner）
各工具会话文件（JSON/SQLite）
-> chokidar 监听
collector.js（tokscale 执行）
-> Token 解析 + 成本计算
usage.js（按时间/工具/设备聚合）
-> SSE 推送 / Hub 上报
Hub 服务器 / Cloudflare Worker
-> 聚合多设备数据
Electron Renderer（GUI 渲染）
模块化程度高：32 个 shared 模块各司其职，clientTracking、sessionDetail、limitCollector 等模块边界清晰，通过 CommonJS 模块系统组合。这种设计使得新增对某个 AI 工具的支持只需添加一个新的 xxxLimits.js 模块，无需修改核心采集逻辑。
测试覆盖完整：使用 Node.js 原生 test runner（node --test），tests/ 目录下按模块分类，单元测试、集成测试均有覆盖。ESLint 代码风格检查加测试验证的 CI 流程确保代码质量。
文档国际化：README 提供英文、简体中文（README.zh-CN.md）和繁体中文（README.zh-TW.md）三个版本，说明作者面向全球中文开发者社区的定位。
cursorAuth.js、copilotDeviceFlow.js 处理各平台 OAuth 流程，Token 不在本地明文存储最简单的方式是直接下载预编译的安装包：
.dmg 安装包，支持 Apple Silicon (arm64) 和 Intel.exe 安装程序预编译包由 electron-builder 打包，体积约 100-200MB（包含完整的 Chromium 运行时）。首次运行后，Widget 会出现在系统托盘，点击图标展开主界面。
git clone https://github.com/Javis603/token-monitor.git
cd token-monitor
npm install
npm start # 运行 Widget
npm run hub # 运行 Hub 服务器
npm run agent # 运行 Agent（无头模式）
npm test # 运行测试
适合服务器和 WSL 环境：
export TOKEN_MONITOR_HUB_URL=http://192.168.1.10:17321
export TOKEN_MONITOR_SECRET=your-secret-key
export TOKEN_MONITOR_INTERVAL_MS=300000 # 5分钟采集一次
npm run agent
Agent 模式会把本机的所有 AI 工具消耗数据上报到 Hub，适合有远程开发机器的团队使用。
Claude Code、Codex、OpenCode 之外的大多数工具（如 Hermes Agent、OpenClaw）只能显示 Token 总量，没有单个 Session 的详细记录。各工具的数据存储格式差异较大，逐一适配需要大量维护工作。作者在代码注释中也明确提到 MiMo Code 有意排除在默认追踪列表外，因为它会重复计算从 Claude Code 导入的会话。
tokscale 是 Token Monitor 的核心技术依赖，它的版本更新直接影响 Token 计算的准确性。虽然项目内置了 tokscale 的自动更新机制（tokscaleUpdater.js），但这引入了额外的外部依赖风险——如果 tokScale 服务不稳定，Token Monitor 的核心功能也将受影响。
作为 Electron 应用，Token Monitor 需要图形运行环境。虽然 Agent 模式提供了 CLI 替代方案，但 GUI 的实时显示体验无法完全复制。对于纯服务器环境的用户，Agent 模式加 Hub 是可行但不够直观的替代路径。
Token Monitor 所在的赛道（AI 工具用量监控）正在快速增长。随着 Claude Code、Copilot Workspace、Cursor 等 AI 编程工具从尝鲜玩具进化为日常生产力工具，Token 成本管理正在成为开发者和企业的真实需求。
类似的产品还有：
Token Monitor 的差异化在于：覆盖面最广（17+ 工具）加 本地优先（不强制云端）加 多设备同步（解决多机器用户痛点）。这三个特性组合在一起，在同类开源项目中暂无直接竞争者。
作者还维护了 worker/ 目录的 Cloudflare Worker Hub 实现，这意味着 Token Monitor 具备完整的云端部署方案：一个开发者可以在 5 分钟内用 Wrangler 将 Hub 部署到 Cloudflare，生成一个 token-monitor-hub.xxx.workers.dev 的地址，然后任意多台设备通过这个地址同步数据，零服务器运维成本。
Token Monitor 解决的是一个非常具体但普遍的问题：当你同时使用多个 AI 编程工具时，如何优雅地知道自己在花钱、花了多少钱、花在了哪个项目上。
它的设计哲学是本地优先、渐进增强：基础功能开箱即用（直接读取本地文件，无需任何配置），高级功能（多设备同步、精确计费）需要按需启用。这种设计降低了使用门槛，同时保留了扩展空间。
对于 AI 开发者而言，Token Monitor 是工具链的有力补充；对于 AI 爱好者而言，它是了解自己 AI 使用习惯的一面镜子。开源加 MIT 许可证加完整的文档和测试，意味着任何人都可以基于它构建自己的用量管理方案。