mcpField
C
contextburn

contextburn

本地服务
arsentev.ai数据与分析03 周前更新
代码仓库访问官网

关于 contextburn

contextburn 分析本地 Claude Code 记录，展示付费 Token 中转化为模型输出的比例，以及重复读取上下文的部分。它为编码 Agent 用户提供会话和成本加权效率报告，且不会通过网络发送数据。

主要功能

  1. 01分析本地 Claude Code 记录
  2. 02统计输出占比与重复读取上下文
  3. 03提供 Token 和成本加权视图
  4. 04查看会话详情与订阅时段
  5. 05支持 JSON 输出和 MCP 工具

适用场景

  1. 01比较不同会话的 Token 效率
  2. 02找出导致上下文膨胀的内容
  3. 03在会话中查看当前用量

MCP 相关

它可启动 stdio MCP 服务，提供 `run_efficiency` 和 `spend_breakdown` 工具，供 Agent 查询运行效率与报告。

配置

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

mcp.json · 通用配置
{
  "mcpServers": {
    "ai-arsentev-contextburn": {
      "command": "uvx",
      "args": [
        "contextburn"
      ]
    }
  }
}
启动命令uvx contextburn

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

安装包
pypicontextburn0.2.1

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

contextburn：24 小时内的实际输出——有用工作占令牌的 0.18%，上下文重读占 98.4%，按成本加权的有用工作占 6.7%，每个有用令牌要付出 555 个令牌的成本

DOI 10.5281/zenodo.22712985

contextburn 会读取 Claude Code 已在你的设备上写入的对话记录，并告诉你付费令牌中有多少转化成了模型输出，以及 Agent 重读了多少已经发送过的上下文。

令牌计数器回答的是 “我花了多少？”。而它回答的是 “其中有多少用于工作？”——以标准化占比呈现，便于跨会话、模型和工作方式比较。

试用

cp bin/contextburn ~/bin/contextburn && chmod +x ~/bin/contextburn   # python3 only, no dependencies
contextburn detail 24

演示

36 次实验运行中第 72 项的 contextburn 详情：168 个会话，有用工作占令牌的 1.44%，上下文重读占 94.4%，按成本加权后为 28.8%

基于 U 曲线报告背后 36 次运行的会话日志生成的实际输出——设备上的其他内容一概不读取。带 DOI 的视频：10.5281/zenodo.22713920。这些运行数据均已开源：Hugging Face（DOI 10.57967/hf/10366）· Kaggle · OSF（DOI 10.17605/OSF.IO/5QTWY）。

为什么有两个数字

相同的 12 项任务，一次长会话与 12 次短会话，每种各运行 3 次：令牌效率为 1.11% 对 1.12%，没有差别；按成本加权的效率为 31.6% 对 24.6%，相差 7 个百分点

  • 按令牌计算，占比几乎不变。Agent 的每一步都会重新发送累积的上下文，因此重读占主导，不论你做什么都是如此——这反映的是 Agent 的特性。
  • 按成本加权，占比确实会变化，因为缓存读取的定价远低于新输入和输出。这取决于你如何运行会话——它反映的是你的使用方式。

以上比较来自一项受控实验，其数据集和分析脚本见：每三项任务清空一次：编码 Agent 上下文经济中的实测 U 曲线。

计数方式

  • 读取本地 Claude Code 对话记录（~/.claude/projects/**/*.jsonl）。数据不会离开设备——完全不会进行网络调用。
  • 按消息 ID 去重使用记录，并保留各元素的最大值。流式运行时会为同一次调用先写入一个早期快照，再写入最终记录：两者都计数会造成重复，只保留第一条则会让输出减半。
  • 成本占比按模型价格加权，价格位于 bin/contextburn 文件顶部。价格变动时，请在此处更新。

命令

命令显示内容
contextburn当前正在消耗令牌的内容
contextburn detail [hours]运行效率、会话，以及具体哪些内容扩大了上下文
contextburn window当前的 5 小时订阅时段
contextburn --json机器可读的状态（菜单栏应用使用）
contextburn --probe <hours>已解析会话的原始 JSON 转储
contextburn --efficiency [hours]以 JSON 格式输出运行效率
contextburn mcp启动 MCP 服务
配置
设置默认值含义
CONTEXTBURN_LANG 或 ~/.config/contextburn/langen界面语言：en 或 ru
CONTEXTBURN_DAY_START6一天开始的时间（小时）——每日总量会在此时重置
CONTEXTBURN_WARN30000000令菜单栏计数器变黄的每小时 token 数
CONTEXTBURN_ALARM90000000令菜单栏计数器变红的每小时 token 数

此语言文件存在的原因是：菜单栏应用由 Finder 启动，而环境变量无法传递给它：运行 echo ru > ~/.config/contextburn/lang 即可切换应用和 CLI 的语言。

MCP 服务

让 Agent 在会话期间读取自身的运行效率。此软件包附带一个无依赖项的 MCP 服务（stdio），提供两个工具：run_efficiency 以结构化数据返回占比，spend_breakdown 则返回完整报告。

claude mcp add contextburn -- uvx contextburn mcp

也可以将其安装为 Claude Code 插件，该插件会注册相同的服务：

/plugin marketplace add arsentev-ai/contextburn
/plugin install contextburn@contextburn

编辑器扩展

菜单栏应用（macOS）

app/main.swift 是一个小型状态栏应用。它每分钟轮询一次 contextburn --json，并显示当前消耗速率和每小时图表；点击柱形即可查看该小时的明细。

swiftc -O -o ContextBurn app/main.swift

如果 CLI 不在 ~/bin 或常见的 Homebrew 路径中，请设置 CONTEXTBURN_BIN=/path/to/contextburn。

限制

  • 目前仅支持 Claude Code 会话记录。
  • 按成本加权的占比是否及时，取决于 bin/contextburn 中的价格表。

引用

软件 DOI（所有版本）：10.5281/zenodo.22712985。GitHub 的 “引用此仓库” 按钮会提供引用信息；元数据位于 CITATION.cff。

作者

Evgenii Arsentev — arsentev.ai · ORCID 0000-0002-9120-7298

此项目发布首日使用的名称是 tokmon，之后为避免与同名的无关工具混淆而更名；TOKMON_* 环境变量仍然有效。

许可证

MIT — 请参阅 LICENSE。

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。