有次让 Claude Code 跑一个稍微复杂的重构任务，七八分钟过去了，终端还在刷。

看不出来它卡在哪。Bash 命令没报错，模型还在输出，但就是慢。是某个文件读了几十遍？还是某个命令在等 IO？还是模型陷进了某个循环？终端输出全是过去式，刷过去就没了。等任务跑完，你也说不清楚时间花在哪段。

后来装了 cctrace，同样的任务，跑完打开瀑布流时间线。一眼看到：有一个 Bash 工具调用卡了将近两分钟，前后各有一批 Read 快速通过，中间夹着十几个工具调用结果。问题从「完全不知道」变成「哦，是这里」。

cctrace 做的事很简单：把整段会话变成你能看懂的瀑布流时间线。

cctrace 瀑布流时间线

一、看不到的东西

用 Claude Code 或 Codex 跑稍微复杂一点的任务，终端里会不停刷新输出。看起来在干活，但你说不清楚：

  • 哪个工具调用耗时最长？是 Read 读了一堆文件，还是 bash 在等某个命令？
  • 模型什么时候在思考，什么时候真的卡住了？
  • 子 agent 是什么时候 fan out 的，fan out 了几层？
  • 一次对话窗口跑了五分钟，wall-clock 时间花在哪段？

这些问题，光看终端输出根本答不上。Claude Code 没有内置 profiler，transcript 文件有，但是一行一行的 JSON，要手动关联事件顺序。ccglass 记录有另一套格式。进程层面的事件又是另一回事。三路数据，散着放。

二、cctrace 怎么解决

cctrace 的做法：在你启动 agent 之前，先套一层包装器。

cctrace claude -- claude

这一行命令之后，cctrace 会同时监控三个来源：

  1. agent 进程本身的活动（process 层）
  2. transcript 文件的写入（transcript 层）
  3. ccglass 的 trace 记录（ccglass 层）

三路事件进同一套 Event / Session 模型，用启发式算法把跨来源的相关事件关联起来，每条关联标四档置信度（exact/likely/possible/unknown）。

然后在本地起一个 web server（默认 127.0.0.1:43179），打印出 URL，浏览器打开就是瀑布流时间线。

没有后台进程，没有遥测，数据只写到本地磁盘的 JSONL 文件。

三、实际能看到什么

瀑布流时间线

左侧按请求轮次分组，每一个事件（用户输入、AI 回复、工具调用、工具结果）都在同一条时间轴上。顶部有整段会话的事件密度总览，可以快速定位哪个时间段最密集。横向拖动缩放，纵向滚动看全部。

单事件详情

cctrace 事件详情

点开任意一条工具操作，可以看：

  • 参数和输出
  • 耗时（start / end timestamp）
  • 关联 ID（与哪些事件有关联、四档置信度标签）
  • 原始事件 JSON

「为什么这个工具调用这么慢」或者「这个工具调用的结果被后面哪个事件用了」，点进去直接看。

回放

每次会话都是磁盘上的 JSONL 文件。跑完之后，随时可以：

cctrace view <session-id>

重新打开，不需要重跑 agent。JSONL 格式，也可以直接 grep、jq 或管道给别的工具处理。

四、怎么用

安装

Go 1.22+ 环境：

go install github.com/androidZzT/cctrace/cmd/cctrace@latest

仅支持 macOS / Linux。

录制 Claude Code 会话

cctrace claude -- claude

CLI 打印出本地 web UI 的 URL，浏览器直接打开。

录制 Codex 会话

cctrace codex -- codex

同一套录制管线，切换 agent 只需要换第一个参数。

回放保存的会话

cctrace view <session-id>

五、几个设计取舍

代码结构按职责拆分：

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…