给 AI 编码 Agent
装一副仪表盘

跑完一个任务，唯一能看见的是终端里最后一行 "Done"。至于：

• 这次会话花了多少 token？多少钱？
• Claude 真的读了那个文件，还是只搜了关键词？
• 它 spawn 了几个 subagent？每个跑了多久？
• 上周这个项目在 AI 编码上的总支出是多少？哪个模型贵？
• 上次改错的地方，是哪次 Edit 调用？参数是什么？

这些问题，官方 UI 都不直接回答。你只能翻 ~/.claude/projects/ 下那堆 JSONL 文件，或者每次会话结束打开 Codex 的 sessions 目录一行行看。

常见场景

五块各自干什么

1. 数据源：两类 AI 编码工具产出三种信号——Claude 的 hook 事件（实时）、Claude 的 JSONL 日志（token 真相）、Codex 的 JSONL 日志（唯一通道）
2. Collectors · 转换层：tm emit 是 hook 的轻量接收端；ClaudeLogWatcher 扫描 JSONL 补 token；CodexWatcher 轮询 Codex 会话目录
3. Daemon：Unix socket 接事件 → 写 SQLite → 广播给订阅者。单例，PID lock 保护
4. SQLite：~/.tokenmeter/data/tokenmeter.db，5 张表装下所有历史
5. Consumers：TUI（bubbletea，4 个 tab）订阅实时事件；Web（嵌入式 SPA + REST API）独立启动

Claude Code 路径：hook + 日志"双通道"

Claude Code 的每个 tool 调用都会 stdin 发一个 JSON 给 TokenMeter 注册的 hook 脚本（PreToolUse 发起前、PostToolUse 完成后）。hook 脚本就是 tm emit——把 stdin 读完，转成事件发到 Unix socket，结束。

但是——hook 本身不携带 token 数量。Claude 只在把会话写 JSONL 时附上 usage。所以 TokenMeter 同时跑一个 ClaudeLogWatcher 扫描 ~/.claude/projects/ 下那些 JSONL 文件，找 type == "assistant" 的行，从 message.usage 把 token 数补进数据库。

Codex 路径：只能扫日志

Codex 没有 hook 机制。TokenMeter 启一个 CodexWatcher 轮询 ~/.codex/sessions/YYYY/MM/DD/*.jsonl。关注三种 payload：

• session_meta → 会话开始
• response_item → 工具调用（function_call 起、function_call_output 完）
• event_msg with type:"token_count" → token 记账

轮询意味着同一份数据可能被读两次。Codex watcher 在内存里维护 lastTokenUsage map 去重，保证不重复计费。

Claude JSONL 的一个小坑 · cwd 编码

Claude 把会话 JSONL 存在 ~/.claude/projects/<cwd-encoded>/<session-id>.jsonl。cwd 的编码规则是：每个 / 替换成 -（含首字符）。比如：

• /Users/admin/code/tokenmeter → -Users-admin-code-tokenmeter

这个细节写在 internal/collector/claude.go 里——错一个字符，就找不到日志文件。

type Event struct {
    ID        string     // tool_use_id (Claude) 或 call_id (Codex)
    Type      EventType  // ToolCallStart | End | AgentStart | ...
    SessionID string
    AgentID   string
    Platform  Platform   // "claude" | "codex"
    Timestamp time.Time
    Data      EventData
}

为什么这样设计

Claude 和 Codex 的原生事件结构完全不一样。Claude 的 hook JSON 有 hook_event_name / session_id / tool_input / tool_use_id；Codex 的 JSONL 里是 timestamp / type / payload 套娃。

如果 daemon、storage、TUI 都分别处理两种原生格式，每加一个平台就要在五个地方改代码。所以 TokenMeter 的第一件事是把它们收敛到统一 Event，后面所有层都只认 Event。

Pre / Post 关联靠 ID 对齐

一次工具调用其实是两个事件：Pre 发起前、Post 完成后。daemon 靠 Event.ID 关联两头，算出 duration_ms。

• Claude 用 tool_use_id（Claude Code 保证全局唯一）
• Codex 用 call_id（函数调用 id）

一条调用 Pre 先到、Post 后到——中间可能隔几秒。daemon 维护一张待配对 map，Post 到时 pop 出来更新那行 tool_calls 记录。

所有历史都落在 ~/.tokenmeter/data/tokenmeter.db，用 modernc 的纯 Go SQLite 驱动。5 张表，职责分明：

Schema 变更原则

internal/storage/db.go 里的 migrate() 函数只用两种动作：

• CREATE TABLE IF NOT EXISTS 建新表
• addColumnIfMissing() 幂等加新列

不允许删列、重命名列。老版本 TokenMeter 的数据库升级到新版本必须能直接打开用。这条纪律让 TokenMeter 敢做"零停机自升级"。

刷新机制：轮询 + 推送

TUI 每 2 秒跑一次 tickCmd 主动查库（兜底），同时订阅 daemon 的实时事件（listenEvents）——有新 hook 事件一到就立刻刷屏。两条路互为保底。

几个贴心细节

• gitBranch 作显示名：原始 session UUID 太丑；优先用 JSONL 顶层的 gitBranch，其次 filepath.Base(cwd)，最后才是 UUID
• 跨视图切会话：[ / ] 在任何 tab 都能切上一个/下一个 session
• Copy 恢复命令：c 键把当前会话的恢复命令拷到剪贴板
• 展开详情不丢：expandedCalls map 按 call_id 持久化，刷新后仍保留哪些调用是展开的

快捷键节选

tm web 启动一个独立的 HTTP 服务（默认 :8370），提供：

• 费用面积图——Canvas 绘制，hover 显示详情，点击某一天按天筛选会话
• 模型占比 + 工具排行——同一屏看清钱花哪了
• 会话列表——搜索、排序、按费用色标
• 会话详情——对话消息、工具时间线、文件变更、Agent 层级
• 深色 / 浅色主题——自动跟随系统偏好
• 键盘导航——j/k 选、Enter 开、/ 搜、←/→ 切、Esc 返回、? 帮助

架构上：独立的进程

Web 不是 TUI 的扩展，是独立进程。它直接读 SQLite（与 daemon 共用同一个 .db 文件），对外暴露 REST API + 嵌入式 SPA（Go embed 打包，不依赖外部静态目录）。

三种身份键

三种典型重复场景

1. daemon 重启——重启后 ClaudeLogWatcher 从头扫 JSONL。没有 source_id 唯一索引，token 会被重新累加一遍。
2. Codex 轮询覆盖——文件还在写，上次轮询读了 80%，这次读了 100%。内存 lastTokenUsage map 记录"这个 key 上次用量是 X"，避免重复计费。
3. Stop hook 重试——Claude 有时会发两次 Stop。MarkPendingToolCallsInterrupted 幂等，跑几次都一样。

僵尸会话的处理

有些会话因为 Claude 进程被 kill、机器休眠等原因没走 SessionEnd，数据库里就挂着 status=running。daemon 每次启动会跑 MarkStaleSessionsEnded(2h)——2 小时没更新的 running 会话，标记为 ended。

每日三件套

报告与清理

守护进程与卸载