coding-agent-session-formats

name

coding-agent-session-formats

description

Use when parsing, exporting, visualizing, or computing token/cost stats from local coding-agent session files (Codex rollout jsonl, Claude Code project jsonl, Kimi context/wire jsonl, OpenCode/zcode SQLite, Pi tree jsonl). Covers storage paths per agent, message schemas, assistant message ordering/dedup rules, a unified export schema, cache-aware cost calculation, and streaming-parse performance rules for 100-400MB files.

Coding Agent 本地会话格式与解析

各家 coding agent 本地会话存储的逆向知识。适用于解析、导出、可视化会话，或做 token/cost 统计。

1. 存储位置（env 优先 → home 兜底）

路径解析设计：官方环境变量优先 → 默认 home → 本地开发目录回退。

Agent	根目录	会话数据	形态
Codex	CODEX_HOME → ~/.codex	sessions/YYYY/MM/DD/rollout-<ISO>-<uuid>.jsonl；标题缓存 .codex-global-state.json	JSONL
Claude Code	CLAUDE_CONFIG_DIR → ~/.claude	projects/<cwd转义>/<sessionId>.jsonl（cwd 的 / 转 -）	JSONL
Kimi	KIMI_SHARE_DIR → ~/.kimi	sessions/<hash>/<uuid>/：context.jsonl(主) + wire.jsonl(事件) + metadata.json	JSONL 目录
OpenCode	XDG_DATA_HOME/opencode → ~/.local/share/opencode	opencode.db（表 session/message/part）	SQLite
zcode	~/.zcode（macOS）/ %USERPROFILE%\.zcode（Win）；Linux 不存在	cli/db/db.sqlite，OpenCode 同范式	SQLite
Pi	~/.pi	agent/sessions/--<path>--/<ts>_<uuid>.jsonl（树状）	JSONL

resume 命令：claude --resume {id} / codex resume {id} / kimi --r {id} / opencode -s {id} / pi --session {id}；Cursor 无。

2. 各格式消息结构

Codex（rollout jsonl）

每行 {timestamp, type, payload}：

• session_meta：{id, timestamp, cwd, ...}。
• response_item（正文）：payload.type = message（role: developer|user|assistant，content[].type = input_text/output_text）、reasoning（summary[].type=summary_text 即 thinking）、function_call/function_call_output（按 call_id 配对）、custom_tool_call(_output)（如 apply_patch）。
• event_msg：UI 事件，与 response_item 内容重复，是主要去重来源。

规则：时间取每行 timestamp；call/output 按 call_id 合并为一个 tool part；工具向上归属——text 之后连续的 tool 挂到该 text，直到下一条 text；工具名 exec_command → bash（function_call 几乎只有它，其余走 custom_tool_call）；role=developer、<INSTRUCTIONS>/<environment_context> 包装的 user 消息应过滤；bash 输出头部噪声（Chunk ID / Wall time / Process exited / Original token count / Output:）展示时剥离；apply_patch 结构化为 write_file（文件+完整内容）/edit_file（按文件 diff）。

Claude Code（jsonl）

每行顶层：parentUuid, isSidechain, cwd, sessionId, version, gitBranch, type(assistant|user|summary), uuid, timestamp, message。

• message.content[]：text/thinking/tool_use{id,name,input}/tool_result{tool_use_id,content}；message.usage{input_tokens,output_tokens,cache...}。
• tool_use 与 tool_result 是两条独立消息（result 在 type:user 里），用 tool_use.id ↔ tool_use_id 关联。
• isMeta: true 是注入消息，过滤；TodoWrite 整体移除；普通工具按 id 把 output 回填进调用。

Kimi（context.jsonl 主，wire.jsonl 回退）

必须以 context.jsonl 为主——只读 wire.jsonl 会把流式中间态扩散成独立消息（实测 184 vs 真实 113 条）。

• context 行 role：user/assistant/tool/_checkpoint/_usage（后两者忽略）。assistant：content[].type = think|text + tool_calls[]（id 如 ReadFile:0）；tool 行用 tool_call_id 关联回填。
• 工具名映射（仅 7 个）：ReadFile→read, Glob→glob, StrReplaceFile→edit, Grep→grep, WriteFile→write, Shell→bash；SetTodoList 过滤。Kimi 无 tool status（默认成功）。
• token 缺失时从 wire.jsonl 事件的 usage{input_tokens,output_tokens} 补，仍缺则按模型价格估算并标记 estimated。

OpenCode / zcode（SQLite）

session（id/directory/title/time_created 毫秒…）+ message.data(JSON: agent,role,time,cost,modelID) + part.data(JSON: type,callID,state,tool,tokens,text)；part.type = tool/text/reasoning/file。

Pi（树状 jsonl）

id/parentId 组树可原地分支；content blocks：text/image/thinking/toolCall；ToolResultMessage{toolCallId,toolName,isError}。其 Usage{input,output,cacheRead,cacheWrite,totalTokens,cost:{...分项}} 自带分项成本，是 cost 建模最佳样板。

3. assistant 消息模式组（跨 agent 统一）

只有 4 种模式，必须严格保序：① thinking ② thinking+text+tool ③ text+tool ④ text。 实现要点：先并 thinking、再并 text、再挂 tool；thinking-only 分组不能吸附 tool——需要「当前分组」与「最近可挂 tool 的 text 分组」两个独立锚点。

4. 统一导出 Schema

顶层：id/title/directory/version/time_created/time_updated/stats/messages；messages[] = role + parts[]（text/reasoning/tool）。 tool part 统一结构：

{ "type": "tool", "tool": "read", "callID": "...", "title": "read",
  "state": { "arguments": {}, "output": [{"type":"text","text":"..."}] },
  "time_created": 0 }

tool output 回填到调用而非独立消息；无法关联的保留为 fallback role=tool 不丢数据。MCP 工具要把 namespace 拼进完整名。

5. Token / Cost 统计

• cache token 必须计入 cost：cost = input×in价 + output×out价 + cache_write×cacheWrite价 + cache_read×cacheRead价。漏算 cache 是「cost 明显过大/对不上」的常见根因。
• 模型别名要归一（如 anthropic--claude-4.6-opus → claude-opus-4-6），价格表用 LiteLLM 快照做离线兜底。
• 区分 cost_source: "recorded" | "estimated"：有原始 cost 用 recorded；缺失按 token×价格估算并透传标记到 UI。
• 逐消息累加，缺失字段按 ?? 0 容错。

6. 解析性能铁律（单文件可达 100-400MB）

• 绝不整读大文件，流式逐行解析。
• Worker 流式解析时用 append-only buffer（引用稳定）+ 版本号信号驱动 UI，禁止每 batch spread 复制历史记录（O(n²)）。
• 聚合/派生数据增量累积（O(delta)），不要每 batch 全量重扫；无过滤条件时统计直接复用 parser 内部 stats（O(1)）。
• 缓存架构：前台只读缓存（SQLite），独立 worker 负责写入；不要做「源文件更新就直读原始」的分叉路径。
• 用多规格基准文件（50/150/300MB + 高记录数小文件）做 benchmark 验证。