有次让 Claude Code 跑一个稍微复杂的重构任务，七八分钟过去了，终端还在刷。
看不出来它卡在哪。Bash 命令没报错，模型还在输出，但就是慢。是某个文件读了几十遍？还是某个命令在等 IO？还是模型陷进了某个循环？终端输出全是过去式，刷过去就没了。等任务跑完，你也说不清楚时间花在哪段。
后来装了 cctrace，同样的任务，跑完打开瀑布流时间线。一眼看到：有一个 Bash 工具调用卡了将近两分钟，前后各有一批 Read 快速通过，中间夹着十几个工具调用结果。问题从「完全不知道」变成「哦，是这里」。
cctrace 做的事很简单：把整段会话变成你能看懂的瀑布流时间线。
一、看不到的东西
用 Claude Code 或 Codex 跑稍微复杂一点的任务，终端里会不停刷新输出。看起来在干活，但你说不清楚：
- 哪个工具调用耗时最长？是
Read读了一堆文件，还是bash在等某个命令？ - 模型什么时候在思考，什么时候真的卡住了？
- 子 agent 是什么时候 fan out 的，fan out 了几层？
- 一次对话窗口跑了五分钟，wall-clock 时间花在哪段？
这些问题，光看终端输出根本答不上。Claude Code 没有内置 profiler，transcript 文件有，但是一行一行的 JSON，要手动关联事件顺序。ccglass 记录有另一套格式。进程层面的事件又是另一回事。三路数据，散着放。
二、cctrace 怎么解决
cctrace 的做法：在你启动 agent 之前，先套一层包装器。
sh
cctrace claude -- claude这一行命令之后，cctrace 会同时监控三个来源：
- agent 进程本身的活动（process 层）
- transcript 文件的写入（transcript 层）
- ccglass 的 trace 记录（ccglass 层）
三路事件进同一套 Event / Session 模型，用启发式算法把跨来源的相关事件关联起来，每条关联标四档置信度（exact/likely/possible/unknown）。
然后在本地起一个 web server（默认 127.0.0.1:43179），打印出 URL，浏览器打开就是瀑布流时间线。
没有后台进程，没有遥测，数据只写到本地磁盘的 JSONL 文件。
三、实际能看到什么
瀑布流时间线
左侧按请求轮次分组，每一个事件（用户输入、AI 回复、工具调用、工具结果）都在同一条时间轴上。顶部有整段会话的事件密度总览，可以快速定位哪个时间段最密集。横向拖动缩放，纵向滚动看全部。
单事件详情
点开任意一条工具操作，可以看：
- 参数和输出
- 耗时（start / end timestamp）
- 关联 ID（与哪些事件有关联、四档置信度标签）
- 原始事件 JSON
「为什么这个工具调用这么慢」或者「这个工具调用的结果被后面哪个事件用了」，点进去直接看。
回放
每次会话都是磁盘上的 JSONL 文件。跑完之后，随时可以：
sh
cctrace view <session-id>重新打开，不需要重跑 agent。JSONL 格式，也可以直接 grep、jq 或管道给别的工具处理。
四、怎么用
安装
Go 1.22+ 环境：
sh
go install github.com/androidZzT/cctrace/cmd/cctrace@latest仅支持 macOS / Linux。
录制 Claude Code 会话
sh
cctrace claude -- claudeCLI 打印出本地 web UI 的 URL，浏览器直接打开。
录制 Codex 会话
sh
cctrace codex -- codex同一套录制管线，切换 agent 只需要换第一个参数。
回放保存的会话
sh
cctrace view <session-id>五、几个设计取舍
代码结构按职责拆分：
swift
cmd/cctrace CLI 入口
└── internal/
├── app 装配 CLI 解析、采集、持久化、server 启动
├── trace 共享的 Event / Session 模型
├── store 把会话和事件落到 session 目录的 JSONL
├── collectors process / transcript / ccglass → trace events
├── correlate 启发式事件关联 + 四档置信度标记
└── server 本地 web UI + 事件 JSON API为什么用 Go？ 单二进制交付，不依赖 Python 环境，不依赖 Node。go install 一条命令装好，没有包管理器冲突。对需要包一层其他进程的 CLI 工具来说，这个约束很实际。
为什么 JSONL 而不是 SQLite？ JSONL 可以直接 grep / jq 查，diff 两次会话很直接，也方便管道给其他工具。不需要专门的查看工具就能读数据。
关联置信度是怎么算的？ 启发式，基于时间邻近 + 事件类型：对 API 请求/响应事件，在时间窗口内找最近的候选父事件（候选类型限 ToolCall/AgentTurn/Skill/Subagent），找到则标 likely，找不到则标 unknown。置信度是四档枚举（exact/likely/possible/unknown），不是数值分。边缘情况可能漏，但漏了会显示 unknown，不会假报 likely。
采集会不会影响 agent 性能？ cctrace 是轻量包装层，采集是异步的，不在 agent 的关键路径上做阻塞操作。
六、小结
cctrace 不做大而全的调试平台，只做一件事：把你已经在跑的 Claude Code / Codex 会话变成可观测的。一个 Go 二进制，MIT 开源。
项目刚开源，还很早期------关联算法、UI、支持的事件类型都有得打磨。欢迎来提 issue 说说你最想看清楚哪一块，或者直接开 PR 一起做；顺手 star 一下也是支持。
GitHub：github.com/androidZzT/...
致谢：cctrace 读取 ccglass 导出的 trace 作为其中一路数据源，命令范式也借鉴了它「包一层、看清楚」的思路。ccglass 是 @jianshuo 的开源项目（MIT），想直接看清 agent 到底给模型发了什么，很值得一看：github.com/jianshuo/cc...