burnmeter

Name: burnmeter
Author: CloudCorpRecords

本地服务

github.com/CloudCorpRecords数据与分析01 周前更新

代码仓库

关于 burnmeter

burnmeter 分析本地 Claude Code 会话日志中的 Token 使用量，展示各类别占比及按模型汇总的总量。它可作为命令行工具或 stdio MCP 服务运行，无需网络访问或 API 密钥。

主要功能

01递归扫描 JSONL 会话日志
02统计输入、输出及缓存 Token
03计算 Token 类别占比
04按模型拆分总量
05跳过格式错误的日志行
06命令行与 stdio MCP 服务

适用场景

01查看本地会话的 Token 效率
02检查各模型的 Token 总量
03分析指定目录中的日志

MCP 相关

stdio MCP 服务提供 `run_efficiency`，用于查看 Token 类别占比；`spend_breakdown` 用于按模型汇总。两种工具均读取本地会话日志且无需参数。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "cloudcorprecords-burnmeter": {
      "command": "npx",
      "args": [
        "-y",
        "@reneturcios/burnmeter"
      ]
    }
  }
}

启动命令npx -y @reneturcios/burnmeter

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@reneturcios/burnmeter0.1.0stdio

ocighcr.io/cloudcorprecords/burnmeter:0.1.0stdio

工具

收录的工具列表 · 更新于 1 周前

此工具无需参数。

详细介绍

burnmeter

burnmeter 会分析本机现有会话日志中的 Claude Code 令牌用量。它会读取 JSONL 会话文件，将每条用量记录中的令牌数相加，并提供两种视图：总量在输出、输入、缓存创建和缓存读取之间的分布（效率视图），以及包含按模型细分的完整总量（明细视图）。同一个二进制文件既提供命令行界面，也提供 stdio MCP 服务。

所有操作都在本地进行。无需网络访问、API 密钥或账户。日志目录取自已设置的 CONTEXTBURN_LOG_DIR；若未设置，则默认为 ~/.claude/projects；程序会递归读取该目录下的所有 *.jsonl 文件。

安装

npx @reneturcios/burnmeter breakdown

也可以运行容器镜像：

docker run -i ghcr.io/cloudcorprecords/burnmeter

容器默认启动 MCP 服务（见下文）。传入 CLI 参数即可将其用作 CLI。请注意，容器会读取容器内部的日志，因此如果要用它处理真实日志，请挂载日志目录，并将 CONTEXTBURN_LOG_DIR 指向挂载目录。

CLI

burnmeter efficiency
burnmeter breakdown
burnmeter breakdown --log-dir ~/somewhere/else

burnmeter --version

两种报告都会输出 JSON。--log-dir 的优先级高于 CONTEXTBURN_LOG_DIR，而后者的优先级高于默认目录 ~/.claude/projects。退出码：成功时为 0，报告失败时为 1，用法错误时为 2。

明细报告包含 logDir、filesScanned、entriesWithUsage、malformedLines、totals（四种令牌计数以及 total_tokens）和 byModel（按模型统计相同的计数，并包含条目数，按令牌总数降序排列）。效率报告包含相同的扫描字段和总量，另有 shares：各类别占令牌总数的百分比，四舍五入到小数点后两位。

条目的计数方式：无效 JSON（或非 JSON 对象）的日志行会被跳过，并计入 malformedLines。如果一条记录包含用量对象，则计为一个条目；用量对象可以位于顶层，也可以位于其 message 下。四种计数 input_tokens、output_tokens、cache_creation_input_tokens 和 cache_read_input_tokens 会被相加；缺失或非数值字段按 0 计算。模型取自 message.model，若不存在则回退到顶层 model，若仍不存在则使用 unknown。不包含用量对象的条目会被忽略。

当目录不存在或未找到用量条目时，报告不会报错，也不会凭空生成数字：总量和占比均为零，报告中会包含 note 字段，说明未找到用量条目以及搜索位置。

MCP 服务

同一个二进制文件提供两种接口。mcp 子命令会启动 stdio MCP 服务：

npx -y @reneturcios/burnmeter mcp

MCP 客户端配置：

{
  "mcpServers": {
    "burnmeter": {
      "command": "npx",
      "args": ["-y", "@reneturcios/burnmeter", "mcp"]
    }
  }
}

若要读取非默认目录中的日志，请在该服务对应的客户端 env 中添加 CONTEXTBURN_LOG_DIR。

工具

根据原始工具的公开规范，这两个工具均不需要参数。

工具	输入	返回内容
`run_efficiency`	（无）	效率报告：总量以及各类别占令牌总数的比例。
`spend_breakdown`	（无）	完整明细报告：总量以及按模型细分的数据。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (temporary fixture logs only)
npm run dev     # run the CLI from source via tsx