introspect

内省

从 Claude Code 会话日志中提取可执行的情报。有关通用 JSONL 分析模式（筛选、聚合、跨文件联接），请参阅 log-ops 技能。

cc-session CLI

scripts/cc-session 脚本提供零依赖分析（仅需 jq + bash）。它会自动解析当前项目和最近的会话。

# Copy to PATH for global access
cp skills/introspect/scripts/cc-session ~/.local/bin/
# Or on Windows (Git Bash)
cp skills/introspect/scripts/cc-session ~/bin/

命令

命令	功能
cc-session overview	条目计数、耗时、工具和思考总数
cc-session tools	工具使用频率（已排序）
cc-session tool-chain	按顺序追踪工具调用，并汇总输入
cc-session thinking	完整的思考／推理内容块
cc-session thinking-summary	每个思考内容块的前 200 个字符
cc-session errors	包含错误模式的工具结果
cc-session conversation	重建的用户／助手对话轮次
cc-session files	已读取、编辑、写入的文件（含计数）
cc-session turns	按轮次细分（耗时、使用的工具）
cc-session agents	子 Agent 启动记录，含类型和提示词预览
cc-session cost	粗略估算 Token／成本
cc-session timeline	带时间戳的事件时间线
cc-session summary	会话摘要（压缩边界）
cc-session search <pattern>	搜索各会话（文本内容）

选项

--project, -p <name>    Filter by project (partial match)
--dir, -d <pattern>     Filter by directory pattern in project path
--all                   Search all projects (with search command)
--recent <n>            Use nth most recent session (default: 1)
--json                  Output as JSON instead of text

示例

cc-session overview                              # Current project, latest session
cc-session tools --recent 2                      # Tools from second-latest session
cc-session tool-chain                            # Full tool call sequence
cc-session errors -p claude-mods                 # Errors in claude-mods project
cc-session thinking | grep -i "decision"         # Search reasoning
cc-session search "auth" --all                   # Search all projects
cc-session turns --json | jq '.[] | select(.tools > 5)'  # Complex turns
cc-session files --json | jq '.edited[:5]'       # Top 5 edited files
cc-session overview --json                       # Pipe to other tools

分析决策树

What do you want to know?
|
|- "What happened in a session?"
|  |- Quick overview ---- cc-session overview
|  |- Full conversation -- cc-session conversation
|  |- Timeline ---------- cc-session timeline
|  |- Summaries --------- cc-session summary
|
|- "How was I using tools?"
|  |- Frequency ---------- cc-session tools
|  |- Call sequence ------- cc-session tool-chain
|  |- Files touched ------- cc-session files
|
|- "What was I thinking?"
|  |- Full reasoning ------ cc-session thinking
|  |- Quick scan ---------- cc-session thinking-summary
|  |- Topic search -------- cc-session thinking | grep -i "topic"
|
|- "What went wrong?"
|  |- Tool errors --------- cc-session errors
|  |- Debug trajectory ---- cc-session tool-chain (trace the sequence)
|
|- "Compare sessions"
|  |- Tool usage diff ----- cc-session tools --recent 1 vs --recent 2
|  |- Token estimation ---- cc-session cost
|
|- "Search across sessions"
|  |- Current project ----- cc-session search "pattern"
|  |- All projects -------- cc-session search "pattern" --all

会话日志架构

文件结构

~/.claude/
|- projects/
|   |- {project-path}/                        # e.g., X--Forge-claude-mods/
|       |- sessions-index.json                # Session metadata index
|       |- {session-uuid}.jsonl               # Full session transcript
|       |- agent-{short-id}.jsonl             # Subagent transcripts

项目路径使用双连字符编码：C:\Projects\my-repo -> C--Projects-my-repo

条目类型

类型	角色	关键字段
user	用户消息 + 工具结果	message.content[].type = "text" 或 "tool_result"
assistant	Claude 响应	message.content[].type = "text"、"tool_use" 或 "thinking"
system	轮次耗时、压缩	subtype = "turn_duration"（含 durationMs）或 "compact_boundary"
progress	Hook／工具进度事件	data.type、toolUseID、parentToolUseID
file-history-snapshot	文件状态检查点	snapshot、messageId、isSnapshotUpdate
queue-operation	消息队列事件	operation、content
last-prompt	最近用户提示词缓存	lastPrompt
summary	压缩摘要	summary、leafUuid

内容块类型（位于 message.content[] 内）

内容块类型	出现位置	字段
text	user、assistant	.text
tool_use	assistant	.id、.name、.input
tool_result	user	.tool_use_id、.content
thinking	assistant	.thinking、.signature

通用字段（所有条目类型）

uuid, parentUuid, sessionId, timestamp, type,
cwd, gitBranch, version, isSidechain, userType

会话日志保留期限

默认情况下，Claude Code 会在启动时删除闲置超过 30 天的会话。延长保留期限，以便留存历史记录用于分析。

// ~/.claude/settings.json
{
  "cleanupPeriodDays": 90
}

当前设为 90 天。请根据磁盘用量调整（dust -d 1 ~/.claude/projects/）。

jq 快速参考

如果 cc-session 无法满足需求，可使用以下命令进行一次性查询：

# Pipe through cat on Windows (jq file args can fail)
cat session.jsonl | jq -r 'select(.type == "assistant") | .message.content[]? | select(.type == "tool_use") | .name'

# Two-stage for large files
rg '"tool_use"' session.jsonl | jq -r '.message.content[]? | select(.type == "tool_use") | .name'

会话洞察

运行任何分析后，始终生成“会话洞察”部分，并提供可执行的建议。语气应友好且具有指导性——像一位发现了一些规律、愿意提供帮助的同事，而不是批评者。

值得关注的方面

扫描会话数据中的以下模式，并在适用时生成建议：

工具使用改进：

• 使用 Bash(grep ...) 或 Bash(cat ...) 代替 Grep/Read 工具——建议改用专用工具
• 多次使用相同输入调用工具但均失败——建议尽早转换思路
• 对于技能可处理的任务，大量使用 Bash——按名称推荐相应技能
• 在可并行执行独立读取/搜索时，没有使用并行工具调用

工作流模式：

• 长时间会话中没有提交——建议逐步提交
• 会话结束时没有使用 /save——提醒保持会话连续性
• 反复重新读取上下文（同一文件读取 3 次以上）——建议记录笔记或使用 /save
• 大段手动工作本可由 /iterate 自动完成——提及循环模式
• 陷入调试循环（针对同一方法尝试 5 次以上）——建议采用 3 次尝试后转换思路的规则

技能和命令使用意识：

• 手动进行代码审查但未使用 /review——提及该技能
• 编写测试但未使用 /testgen——提及该技能
• 复杂推理未使用 /atomise——对于难题，提及该技能
• 为技能已能处理的任务启动 Agent——建议使用更轻量的方案

会话效率：

• 会话特别长（工具调用 100 次以上）——建议拆分为多个目标明确的会话
• 错误率较高（超过 30% 的工具调用返回错误）——指出这一模式并建议调查原因
• 文件读取与编辑的比例过高（超过 10:1）——可能表明缺乏方向，建议先制定计划

权限建议： 这项价值很高——权限提示会打断工作流程并占用上下文。扫描会话中的以下内容：

• 多次成功使用的 Bash 命令——这些命令可考虑加入 Bash(<command>:*) 允许规则
• 频繁出现的工具模式（WebFetch、WebSearch、特定 MCP 工具）——建议将其加入允许列表
• 因权限错误而失败或重试的命令——可能是缺少权限导致的

为 .claude/settings.local.json 生成可直接粘贴的 permissions.allow 片段：

**Permissions**

Based on this session, these tools were used frequently and could be
pre-approved to reduce interruptions:

Add to `.claude/settings.local.json` under `permissions.allow`:
  "Bash(uv:*)",
  "Bash(pytest:*)",
  "Bash(docker:*)",
  "WebSearch",
  "mcp__my-server__*"

This would have saved roughly ~N permission prompts in this session.

只推荐实际成功使用过的命令——切勿建议使用宽泛的 Bash(*)。但在合理的情况下，应鼓励使用通配符模式——Bash(git:*) 比分别列出 Bash(git status)、Bash(git add)、Bash(git commit) 更好。常见的通配符组：

• Bash(git:*)——所有 git 操作
• Bash(npm:*)、Bash(pnpm:*)、Bash(uv:*)——包管理器
• Bash(pytest:*)、Bash(jest:*)——测试运行器
• Bash(docker:*)、Bash(cargo:*)、Bash(go:*)——构建/运行时工具
• mcp__server-name__*——某个 MCP 服务的所有工具

为清晰起见，按类别整理建议。如果列表较长，请参阅 /setperms 了解完整的权限设置。

输出格式

## Session Insights

Here are a few things I noticed that might help next time:

**[Category]**
- [Observation]: [What was seen in the data]
- [Suggestion]: [Friendly, specific recommendation]

**[Category]**
- ...

根据会话规模调整建议数量。10 分钟的快速会话可能只需要 1-2 条观察结果；持续数小时且工具调用超过 100 次的大型会话，则可能有 10-15 条可执行的建议。分析深度应与会话内容相匹配。

只提及数据中明确存在的模式——不要猜测或牵强附会。如果会话干净且高效，请说明：“这是一次组织良好的会话——没有明显需要改进的地方。”

参考文件

文件	内容
scripts/cc-session	CLI 工具——提供 14 个命令进行会话分析，支持 JSON 输出和项目筛选
references/session-analysis.md	用于执行 cc-session 无法涵盖的自定义分析的原始 jq 配方

另请参阅

• log-ops——通用 JSONL 处理、两阶段流水线、跨文件关联
• data-processing——使用 jq 和 yq 处理 JSON/YAML/TOML