codex-wait

codex-wait 是一个零依赖的 Node.js CLI，用本机 Codex 会话记录统计每天等待 Codex 完成任务的时间。

统计口径

• 一轮等待从 task_started 开始，到 task_complete 结束。
• 使用完成事件中的 duration_ms 作为任务时长。
• 默认排除 thread_source=automation 的 Codex 定时任务；使用 --include-automations 可计入。
• 跨午夜任务会按指定时区切分到各自然日。
• 默认不计入尚未完成的任务；传入 --include-active 后会计到命令运行时刻。
• 启用 --token 时，进行中或中断任务已经产生的 Token 仍会计入；--include-active 只控制等待时长。
• 只有未归档且最近 30 分钟仍有事件的未完成任务才判定为“进行中”；历史未闭合记录会被忽略。
• 默认只解析任务边界和耗时字段；即使启用 Token，也不会读取或输出用户提示词、助手回复、工具输入输出。
• Token 默认不解析、不显示。显式传入 --token 后，才会根据相邻 token_count.total_token_usage 累计快照的增量，按事件实际发生的自然日统计输入、缓存输入、输出、推理输出和总量；累计值缺失时才回退到 last_token_usage。原有 --tokens 仍作为兼容别名可用。

缓存输入 Token 是输入 Token 的子集，推理输出 Token 是输出 Token 的子集，不能把这些字段再次加到总量中。 Token 是可选实验统计，归档会话的用量事件可能不完整，结果仅供参考。表格中百万级 Token 使用 M，达到一亿时同时显示两种单位，例如 350.04M（3.50亿）；启用 Token 后，JSON 和 CSV 保留原始整数。

这里的“等待”是墙钟时间，不是模型纯推理时间。若任务执行期间 Codex 等待用户确认或用户追加输入，这段时间也会包含在内。

环境要求

• Node.js 18 或更高版本
• Codex 本地会话目录，默认是 ~/.codex

安装

推荐直接安装 GitHub Release 中的最新版（需要 Node.js 18+）：

npm install -g https://github.com/ifzc/codex-wait/releases/latest/download/codex-wait.tgz
codex-wait --help

以后如果发布到 npm，也可以执行：

npm install -g codex-wait

所有历史安装包和校验文件可在 GitHub Releases 下载。

从源码安装时，在项目目录执行：

npm install -g .
codex-wait --help

不全局安装也可以直接运行：

node .\bin\codex-wait.js --today

常用命令

# 最近 7 天（默认）
codex-wait

# 今天，包含当前仍在执行的任务
codex-wait --today --include-active

# 最近 30 天
codex-wait --days 30

# 可选显示 Token（归档历史可能不完整）
codex-wait --days 30 --token

# 包含 Codex 定时任务
codex-wait --days 30 --include-automations

# 指定自然日范围和时区
codex-wait --since 2026-08-01 --until 2026-08-31 --timezone Asia/Shanghai

# 逐任务明细（不会显示对话正文）
codex-wait --days 7 --details

# 机器可读格式
codex-wait --all --json > codex-wait.json
codex-wait --days 30 --csv > codex-wait.csv

# 使用其他 Codex 数据目录
codex-wait --codex-home D:\path\to\.codex

JSON 输出包含毫秒级原始数值、逐日汇总、逐任务元数据和扫描诊断信息。CSV 输出一行对应一个自然日。

日期口径

• 所有日期都按 --timezone 指定的 IANA 时区计算，默认使用系统时区。
• --today 是所选时区的今天。
• --days N 包含今天，例如 --days 7 是今天及之前 6 个自然日。
• --since 和 --until 都包含指定当天；--since 单独使用时默认截止今天。
• --until 单独使用时从本地最早记录统计到指定日期。
• --all 统计本地保存的全部会话历史。
• 等待时长跨午夜时会切分到两个自然日；启用 Token 后，按每条用量事件实际发生的日期归属。

开发与验证

npm test
node .\bin\codex-wait.js --codex-home .\test\fixtures\codex-home --days 7

CLI 以流式方式扫描 sessions 和 archived_sessions 下的 .jsonl 文件，不会一次性把会话文件加载到内存。

发布到 npm

项目已将发布目标固定为 npm 官方仓库。首次发布前先登录，然后发布：

npm login --registry=https://registry.npmjs.org/
npm publish

每次再次发布前，需要先递增 package.json 中的版本号。