cc-history

用途

cc-history 是一份参考文档，用于查询和分析 Claude Code 的对话历史文件。它通过 shell 命令与 jq 从 JSONL 对话文件中提取信息。

目录结构

对话历史位于 ~/.claude/projects/{encoded-path}/ 下，包含：

• {session-uuid}.jsonl：主对话
• {session-uuid}/subagents/agent-{hash}.jsonl：子代理对话
• {session-uuid}/tool-results/：大型工具输出

项目路径解析

将工作目录转换为项目目录：

PROJECT_DIR="~/.claude/projects/$(echo "$PWD" | sed 's|^/|-|; s|/\.|--|g; s|/|-|g')"

编码规则：开头的 / 变为 -；普通 / 变为 -；/.（隐藏目录）变为 --。例如 /Users/bill/.claude 对应 -Users-bill--claude，/Users/bill/git/myproject 对应 -Users-bill-git-myproject。

消息类型

• user：用户输入消息
• assistant：模型响应（thinking、tool_use、text）
• system：系统消息
• queue-operation：后台任务通知（子代理完成）

消息结构

JSONL 文件每行是一个消息对象，包含 type、uuid、parentUuid、timestamp、sessionId 以及 message（含 role、content、usage）。usage 中包含 input_tokens、output_tokens、cache_read_input_tokens、cache_creation_input_tokens。

assistant 消息的 content 块类型包括：thinking（含 thinking 字段）、tool_use（含 name、input 字段）、text（含 text 字段）。

常用查询

查找对话：可按修改时间列出（ls -lt）、按日期查找、按内容查找（grep -l）。

提取消息：可按行号（sed -n '42p'）、按 uuid、按类型（user/assistant）提取。

工具调用分析：可列出所有工具调用、按名称计数、查找特定工具调用（如 Bash）。

技能调用检测：模式为 python3 -m skills\.([a-z_]+)\.，可查找所有技能调用或使用特定技能的对话。

Token 用量：可统计对话总 token、token 明细（input/output/cached）、随时间变化的 token 进展。

分类聚合：可按类型统计消息数量、统计用户消息字符数、统计 thinking 块字符数。

子代理分析：可列出会话的子代理、获取子代理任务描述（首条用户消息）、在父对话中查找 Task 工具调用。

对话分支

每个 .jsonl 文件包含整个对话树（所有分支），而非每个分支单独文件。分支通过 parentUuid 追踪：用户回退历史并发出新命令时，新消息获得与分支点相同的 parentUuid；共享同一 parentUuid 的多条消息即为兄弟分支（分叉点）。

检测分支点：可查找所有分叉点（有多个子节点的消息），或展示已知分叉点的兄弟消息。

提取单一分支：先找到该分支中的唯一标识符，再沿祖先链回溯到根。步骤包括：找到目标消息 uuid（按唯一内容或时间戳前缀）、提取分支为 JSONL 流（提供 extract_branch 函数）、执行常见分支查询（消息数、仅用户消息、工具调用、首末消息）。

工作流：定位与探索

1. 查找对话文件（grep -l）
2. 查找匹配消息（可能显示多个分支）
3. 从目标分支选取 uuid 后查询

关联

子代理文件（agent-{hash}.jsonl）不直接链接到父 Task 调用。关联方法：列出 {session}/subagents/ 下所有子代理文件；读取每个文件的首条用户消息以获取任务描述；将描述与父对话中的 Task tool_use 块匹配。