TurnScope

· MIT License · English

TurnScope 是用于分析 Codex 本地会话耗时的只读终端工具。它关联 rollout 记录、thread 元数据与 SQLite telemetry，以 Turn 为单位展示耗时、Tool 活动、Skill 与 MCP 归因以及 Token 用量。

所有分析均在本机完成。TurnScope 不修改 Codex 状态，也不传输会话数据。

运行要求

• 本地 Codex 状态目录，其中包含 state_5.sqlite、logs_2.sqlite 和会话 rollout 文件
• 使用 npm 安装时需要 Node.js 18 或更高版本；从源码安装时需要 Go 1.26 或更高版本

默认状态目录为 ~/.codex。

安装

通过 npm 安装 TurnScope：

npm install --global turnscope
turnscope --latest

也可以直接运行：

npx turnscope --latest

npm 包支持 macOS、Linux 和 Windows 的 ARM64 与 x64 平台。六个平台的原生二进制均包含在唯一的 turnscope 包中，安装过程不执行额外的下载脚本。

通过 Go 安装：

go install github.com/tageecc/turnscope/cmd/turnscope@latest

从源码构建：

git clone https://github.com/tageecc/turnscope.git
cd turnscope
make build

使用

打开会话选择器：

turnscope

打开最新会话、指定 thread 或指定 Turn：

turnscope --latest
turnscope --thread THREAD_ID
turnscope --thread THREAD_ID --turn 0

直接输出报告，不启动 TUI：

turnscope --latest --plain

命令行选项

| 选项 | 说明 | 默认值 | | --- | --- | --- | | --codex-home PATH | Codex 状态目录 | ~/.codex | | --thread ID | 打开指定 thread | 会话选择器 | | --latest | 打开最近更新的 thread | 关闭 | | --turn N | 打开从 0 开始编号的 Turn | 最后一个 Turn | | --plain | 输出文本报告，不启动 TUI | 关闭 | | --no-motion | 关闭 TUI 动效 | 关闭 | | --limit N | 会话选择器最多加载的会话数 | 100 | | --version | 输出版本信息 | 关闭 |

视图

| 视图 | 展示内容 | | --- | --- | | Overview | Turn 总耗时、首 Token、首段可见输出、Tool wall time、Model / orchestration 残差和数据源统计 | | Timeline | 已记录事件的 Waterfall、并行 Tracks 和比例 Flame Allocation | | Tools | Tool 名称、来源、记录耗时、相对耗时占比和 Skill 归因 | | Skills | direct/inferred 归因、调用次数、Tool 累计耗时以及首个到最后一个归因调用的 wall span | | MCP | Server readiness、Tool cache 状态、可用 Tool 数、调用次数和调用耗时 | | Tokens | Input、cached input、total output、reasoning output、estimated visible output、上下文占用和吞吐率 |

在 Timeline 中选中事件并按 Enter 可打开详情。Tool 事件会在相应字段可用时显示已记录的 Input、Output 预览、路由信息、状态和总耗时。Summary、Input 和 Output 页面只展示 Codex 本地记录中实际存在的数据；加密的 Reasoning payload 不会被解码。

Timeline 快捷键

| 按键 | 操作 | | --- | --- | | v | 在 Waterfall、Tracks 和 Flame Allocation 之间切换 | | j/k、↑/↓、,/. | 选择事件 | | h/l | 平移时间窗口 | | +/- | 围绕当前事件缩放 | | f | 聚焦当前事件；再次按下恢复整个 Turn | | / | 按事件、Tool、Skill、MCP、详情文本或 Call ID 筛选 | | c | 只显示包含耗时区间的事件 | | Enter | 打开或关闭事件详情 | | Tab、Shift+Tab | 切换详情页 | | s、i、o | 打开 Summary、Input 或 Output | | PgUp/PgDn、Ctrl+U/Ctrl+D、Home/End | 滚动详情 |

使用 ←/→ 或 1–6 切换主视图，[/] 切换 Turn，r 重新加载数据，Esc 返回上一层。

计时口径

| 指标 | 定义 | | --- | --- | | Turn duration | 已完成 Turn 使用 task_complete 记录的 duration_ms；仍在运行且缺少 task_complete 时，使用 task_started 到最后一条已记录事件的区间。 | | Time to first token | Codex 在 Turn 完成时记录的 time_to_first_token_ms，该时间点可能早于首段可见文本。 | | First visible output | task_started 到第一条 response.content_part.added 的区间。 | | Tool cumulative time | 当前 Turn 内所有 Tool 调用时长之和，重叠调用分别计入。 | | Tool wall time | Tool 执行区间的并集，并发调用的重叠部分只计一次。 | | Visible output time | 第一条 response.content_part.added 到最后一条 response.output_text.done 的区间。 | | Model / orchestration | max(0, Turn duration - Tool wall time - Visible output time)。该残差可能包含请求传输、服务端等待、上下文处理、模型推理和客户端编排，不等同于模型推理耗时。 | | Flame Allocation | 按比例展示 Model / orchestration、Tool wall time 和 Visible output time，并非 CPU 采样调用栈。 |

依赖缺失 telemetry 的指标保持为空，不使用估算值补全。

数据处理

TurnScope 读取以下文件：

~/.codex/sessions/**/rollout-*.jsonl
~/.codex/state_5.sqlite
~/.codex/logs_2.sqlite

SQLite 使用 mode=ro 和 query_only(1) 打开，同时兼容数据库位于 ~/.codex/sqlite/ 的目录结构。

每次 Tool 调用最多保留 64 KiB Output 作为内存预览，报告元数据仍记录完整大小。Reasoning 详情仅包含 Codex 已落盘的明文 summary 或 content。

会话记录可能包含 Prompt、Tool 参数、Output 和本地路径。复制或公开详情前应检查相关内容。

开发

make test
go test -race ./...
go vet ./...
make build
make npm-test
make npm-packages

贡献规范见 CONTRIBUTING.md，漏洞报告方式见 SECURITY.md。

许可证

MIT

TurnScope 是独立项目，与 OpenAI 没有隶属关系。