Tokmeter — AI Agent Usage & Cost

---

为什么需要

每个 Agent 都会单独向你收费，也只展示自己的那部分数据。Claude Code 知道 Claude Code 花了多少钱，Codex 知道 Codex 花了多少钱。但没有任何工具知道今天总共花了多少，哪个项目在悄悄消耗最多，或者你切换到的模型是否确实更适合你的工作、成本也更低。

Tokmeter 会根据磁盘上已有的数据给出答案。它会解析每个 Agent 的本地会话日志，按照实时模型目录计算费用，并维护一份只追加的每日账本，因此即使 Agent 轮换并删除自己的日志，历史记录也能保留下来。

npx @sriinnu/tokmeter --today

文档和主题图库：tokmeter.srinivas.dev。

效果预览

CLI — 按项目、模型和提供方查看用量	摘要 — 每周报告卡片

此外还有一个终端 UI（tokmeter-tui）、本地 Web 仪表盘、Claude Code 状态栏，以及一个 MCP 服务，让 Agent 能查询自身的开销。

安装

需要 Node.js 18+。读取会话文件无需提供方凭据；查询价格时会获取公开目录，而 --light 会完全跳过价格查询。

# Try it without installing
npx @sriinnu/tokmeter --today

# Install the CLI, and the daemon/MCP server
npm install -g @sriinnu/tokmeter @sriinnu/tokmeter-mcp

软件包	内容
@sriinnu/tokmeter	核心 API、CLI 和终端 UI
@sriinnu/tokmeter-mcp	MCP 服务、守护进程、状态栏和实时终端 UI

packages/core、packages/cli 和 packages/tui 是打包进 @sriinnu/tokmeter 的私有工作区软件包。packages/web 是独立的私有工作区应用，需从源代码运行。

若要让守护进程始终运行（使菜单栏和状态栏在重启后继续工作），请安装一次 launchd Agent：tokmeter-mcp daemon install-agent（macOS）。它会在登录时自动启动，并在崩溃后重新启动。

Claude Code 和 Codex 是主要的验证目标。其他解析器及其已知限制，请参阅提供方兼容性。

CLI

tokmeter --today
tokmeter models --project my-app --json
tokmeter daily --week
tokmeter projects
tokmeter stats --month
tokmeter digest --period week
tokmeter pricing sonnet

筛选条件包括 --project、--claude、--codex、--week、--month 和 --since YYYY-MM-DD --until YYYY-MM-DD。使用 --json 输出机器可读的数据，使用 --light 仅输出令牌报告。

• 别名：合并显示名称、为项目添加标签，或将项目从列表中隐藏。
• 备份与恢复：便携式快照、清理预览和恢复。清理会删除源文件；请保留确认和备份步骤。
• CLI 参考：每条命令及其示例。
• 数字的计算方式：各类别的含义以及估算值的来源。

TypeScript API

根导出提供核心 API。便捷查询助手使用 /cli 子路径。

import { TokmeterCore } from "@sriinnu/tokmeter";
import { loadTokmeterSummary } from "@sriinnu/tokmeter/cli";

const core = new TokmeterCore();
await core.scan({ providers: ["codex", "claude-code"], today: true });
const models = core.getModelCosts();
const daily = core.getDailyBreakdown();

const summary = await loadTokmeterSummary({ week: true, light: true });

查询多个细分数据时，请复用一次核心扫描。参阅集成指南、核心 API 用法和 SKILL.md，了解面向 Agent 的集成说明。

守护进程、MCP 和状态栏

tokmeter-mcp daemon start
tokmeter-mcp daemon status
tokmeter-mcp serve             # MCP server over stdio
tokmeter-mcp statusline        # one statusline tick
tokmeter-mcp live              # live terminal UI

守护进程使用本地 HTTP 端口 9877 处理查询，并使用 WebSocket 端口 9876 进行实时注册。私有读取和 WebSocket 连接需要使用每位用户的令牌 ~/.tokmeter/daemon/daemon.token；/api/ready 是公开的健康检查接口。macOS 应用、状态栏和 MCP 服务会在使用时读取该凭据。守护进程命令属于 @sriinnu/tokmeter-mcp；请安装此包以使用这些功能。

MCP 工具使用 tokmeter_ 前缀，涵盖用量查询、比较、预测、导出以及经确认的清理和恢复操作。请参阅按用途分组的 MCP 工具参考，了解全部 24 个工具；配置和程序化导出请参阅包的 MCP README。

tokmeter-mcp editors 会列出安装目标。tokmeter-mcp install-mcp 和 tokmeter-mcp install-statusline 会写入编辑器配置；请检查为你的编辑器生成的设置。对于 Claude Code，请使用 claude mcp add tokmeter --scope user -- npx -y @sriinnu/tokmeter-mcp serve 注册 MCP 服务（从 1.15.0 开始，install-mcp 会自行运行 claude mcp add；1.14.1 及更早版本会将条目写入 ~/.claude/settings.json，而 Claude Code 不会读取该文件）。有关注册、身份验证、刷新、存储和守护进程生命周期的详细信息，请参阅架构。

终端和 Web 界面

# After installing @sriinnu/tokmeter
tokmeter-tui

# Without a global install
npx -p @sriinnu/tokmeter tokmeter-tui

终端 UI 支持概览、模型、每日、统计和清理视图。请参阅其按键和命令。

从源代码检出目录运行 Web 工作区：

bun install
bun run dev:web

打开 http://localhost:3000。有关 Web 设置和数据源，请参阅 Web 设置与数据源。

macOS 应用

发行版本面向 Apple silicon 和 macOS 14 及更高版本。本地守护进程还需要 Node.js 18 及更高版本和 npx。

安装 @sriinnu/tokmeter-mcp，运行 tokmeter-mcp daemon start，然后从 /Applications 打开 TokmeterBar。请从 GitHub Releases 下载应用。

弹出窗口将今日的令牌数和预估 API 费用置于同等显著的位置，下方显示模型和项目。将鼠标悬停在图表上，会显示每日令牌数和费用的精确值。Usage details 会展开累计总量、趋势和信号。主题包括：Terminal、Paper、Prism、Lagoon、Carbon、Glass，以及（自 1.15.0 起）仪表主题 Meter、Pump、Rams、Deck 和 Passbook。模型标题中的 $/M 按钮会显示每个模型的每百万令牌标价（输入、输出、缓存读取、缓存写入）及价格来源，并且仪表板端口可配置。Hub 提供更详细的分类和设置。Settings → Open web dashboard 会按需启动本地服务器；点击 Stop web dashboard 或退出应用会将其停止。

请参阅 macOS 构建和运行时详情、首次使用检查和弹出窗口验证。完成情况跟踪表记录了尚待完成的新机器、可靠性、更新、核算、无障碍功能和试用版相关检查。

合成演示介绍了示例图片的生成方式；这些图片并非当前本地候选版本的截图。

文档

• MCP 工具参考 — 全部 24 个 tokmeter_ 工具，按组列出
• 使用 tokmeter — MCP、守护进程 HTTP、CLI 和进程内集成
• 数字的计算方式 — 数据桶语义及估算值的来源
• 备份、快照与恢复 — 确认和备份模型，以及跨机器恢复
• 故障排查 — 守护进程、菜单栏更新、“历史数据减少”、性能
• 架构 — 守护进程生命周期、存储和刷新

隐私

所有操作都在你的设备上运行。Tokmeter 会读取 Agent 已写入的会话文件，无需提供商凭据、不会发送遥测数据，也无需账户。唯一的对外请求是可选的公开模型价格目录获取操作，使用 --light 时会完全跳过。你的使用数据绝不会离开设备。

支持

Tokmeter 免费且开源。如果它帮你省了钱，不妨捐助我们，以便持续维护：

• GitHub Sponsors
• Buy Me a Coffee

许可证

AGPL-3.0-only。如果你将 Tokmeter 嵌入其他产品，请参阅许可说明，了解相关影响。