Skip to content

About

Local per-turn token usage, elapsed time and throughput for Codex CLI and Desktop. Preview.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Codex 每轮用量统计

0.3.0-preview · MIT · Python 3.9+ · Codex CLI / Desktop

当前是预览版:支持逐轮采集和统计面板自动刷新;尚未实现每轮原生回复末尾自动展示统计。

每轮独立记录输入、缓存读取/写入、输出、推理、总 token、整轮耗时、首 token 时间和平均 tok/s。所有数据来自本地 Codex 记录,不读取 API Key,不上传对话,不额外调用模型。

安装

下载并解压源码,在目录内运行:

python3 install.py

要求 PATH 中已有 codex。安装器复制 turn_stats.py、mcp_server.py、stats.html 到 $CODEX_HOME/codex-turn-stats/(默认 ~/.codex),保留原有 hooks,并用 Codex CLI 注册独立的 codex_turn_stats MCP 服务。遇到同名但指向其他程序的服务会拒绝覆盖。原有 hooks 首次修改前会备份。

首次安装后,在 Codex 的 /hooks 审核并信任 codex-turn-stats。重新加载 MCP/会话,让新工具可用;安装器不修改信任缓存。

python3 install.py --check
python3 install.py --uninstall

卸载仅移除本工具的 hooks 和对应 MCP 注册,保留历史统计、备份及用户其他配置。安装器当前面向 macOS/Linux;Windows 尚未验收。

展示方式和实际支持范围

CLI

Stop/Interrupt hook 在每轮结束/中断时计算统计并返回 systemMessage。具体文字呈现由客户端决定。

桌面版逐轮面板

调用 codex_turn_stats.show_probe,参数包含明确的 thread_id。第一次打开后,面板在可见时每 5 秒查询一次:完成一轮就增加一条独立统计,不需要每轮手动查询,也不创建新的模型轮次。

默认每页 20 轮,可加载更早轮次;历史记录按稳定轮次 ID 去重。中断轮次会标明数据可能不完整。切换到其他会话时,需打开属于该会话的面板,服务不会猜测全局最新会话。

固定到一轮的卡片

在工具参数中同时传 thread_id 和 turn_id。该卡片只显示指定轮次,后续轮次不会覆盖它。若指定轮次尚未结束,显示暂估数据并查询更新;完成记录落盘后自动校正。已完成卡片停止定时查询,仍可手动刷新以获取迟到的用量。

原生回复末尾自动插卡:尚不支持

本包没有实现“每条原生助手回复结束后自动创建新的 MCP UI 卡片”。它与“已打开的面板自动增加统计”是不同能力。

已用 Codex 0.162.1 和本机模拟模型实测:Stop 的 mcp_tool 可以执行成功,但只产生 hook/started、hook/completed 和 warning,没有产生普通的 mcpToolCall UI item。官方源码中 hook executor 只提取文本并按 hook JSON 解析;mcpServer/tool/call RPC 只返回结果,也不会补建 UI item。不能通过切换一个 hook 字段就完成自动原生插卡。

详见 验证记录。官方界面协议或宿主增加相应能力前,不把此项宣传为已实现。不会通过额外模型轮次伪造自动统计,也不会改写原生对话历史或修改桌面程序。

每轮数据

Stop/Interrupt 执行时按以下位置原子写入独立 JSON:

$CODEX_HOME/codex-turn-stats/turns/<thread_id>/<turn_id>.json

重复触发只更新同一轮次;不同会话互不覆盖。记录只包含 ID、状态、模型、用量和时间,不含对话正文或原始文件路径。已完成记录不会被暂估记录降级覆盖。MCP 读取完成记录后会校正暂存统计。

last-hook.json 仅是最近一次执行诊断;查看全部轮次应使用逐轮文件或面板。并发轮次可能覆盖最近一次诊断,不影响独立轮次文件。

统计口径

  • 输入含重复发送的历史上下文与工具结果。缓存读取、写入是输入的细分,不再次加总。
  • 输出含推理 token,推理作为细分展示,不再次加总。
  • 优先使用 turn_token_usage,旧格式使用本轮累计值差额。重复用量快照不会重复相加。
  • 子代理按 session_id / root_turn_id 归属,按线程、轮次、响应 ID 去重后合并。
  • 平均速度 = 本轮输出(含已归属的子代理和推理)÷ 整轮耗时,分母包含思考、工具执行与等待。
  • 完成记录采用运行时 duration_ms。Stop 时尚未落下完成记录的值标记 ≈;固定卡片后续自动校正。
  • 仅有真实 time_to_first_token_ms 时显示首 token;未知用量显示“未知”。不换算金额。

服务商未返回的用量、另外计费的搜索/图片服务、命令内独立调用的 API,不能从 Codex token 记录恢复。旧版子代理缺少归属标识时无法可靠合并。后台子代理晚于主轮次完成时,后续用量需重新读取。transcript 不是稳定 API,Codex 升级可能需要适配。

MCP 参数

{"thread_id": "当前会话 UUID"}
{"thread_id": "当前会话 UUID", "turn_id": "指定轮次 ID"}

分页查询传上一页返回的 next_before_turn_id 作为 before_turn_id;固定轮次与分页参数不能同时使用。UI 支持模型/应用双可见工具,页面查询直接读取本地统计。

手动查看与测试

python3 turn_stats.py /absolute/path/to/rollout.jsonl --turn TURN_ID
python3 turn_stats.py /absolute/path/to/rollout.jsonl --json
python3 -m unittest -v
node test_ui.cjs

当前源码包保留兼容插件布局、hook 定义与查询 Skill。脚本安装是已实现的安装路径;插件 marketplace 分发仍需单独验收,不要同时用两条路径安装以免重复 hook。

参考:Hooks、MCP UI、Plugin Extensions。

About

Local per-turn token usage, elapsed time and throughput for Codex CLI and Desktop. Preview.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages