introspect

Introspect

Extract actionable intelligence from Claude Code session logs. For general JSONL analysis patterns (filtering, aggregation, cross-file joins), see the log-ops skill.

cc-session CLI

The scripts/cc-session script provides zero-dependency analysis (requires only jq + bash). Auto-resolves the current project and most recent session.

# 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/

Commands

Command	What It Does
cc-session overview	Entry counts, timing, tool/thinking totals
cc-session tools	Tool usage frequency (sorted)
cc-session tool-chain	Sequential tool call trace with input summaries
cc-session thinking	Full thinking/reasoning blocks
cc-session thinking-summary	First 200 chars of each thinking block
cc-session errors	Tool results containing error patterns
cc-session conversation	Reconstructed user/assistant turns
cc-session files	Files read, edited, written (with counts)
cc-session turns	Per-turn breakdown (duration, tools used)
cc-session agents	Subagent spawns with type and prompt preview
cc-session cost	Rough token/cost estimation
cc-session timeline	Event timeline with timestamps
cc-session summary	Session summaries (compaction boundaries)
cc-session search <pattern>	Search across sessions (text content)

Options

--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

Examples

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

Analysis Decision Tree

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

Session Log Schema

File Structure

~/.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

Project paths use double-dash encoding: X:\Forge\claude-mods -> X--Forge-claude-mods

Entry Types

Type	Role	Key Fields
user	User messages + tool results	message.content[].type = "text" or "tool_result"
assistant	Claude responses	message.content[].type = "text", "tool_use", or "thinking"
system	Turn duration, compaction	subtype = "turn_duration" (has durationMs) or "compact_boundary"
progress	Hook/tool progress events	data.type, toolUseID, parentToolUseID
file-history-snapshot	File state checkpoints	snapshot, messageId, isSnapshotUpdate
queue-operation	Message queue events	operation, content
last-prompt	Last user prompt cache	lastPrompt
summary	Compaction summaries	summary, leafUuid

Content Block Types (inside message.content[])

Block Type	Found In	Fields
text	user, assistant	.text
tool_use	assistant	.id, .name, .input
tool_result	user	.tool_use_id, .content
thinking	assistant	.thinking, .signature

Common Fields (all entry types)

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

Session Log Retention

By default, Claude Code deletes sessions inactive for 30 days (on startup). Increase to preserve history for analysis.

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

Currently set to 90 days. Adjust based on disk usage (dust -d 1 ~/.claude/projects/).

Quick jq Reference

For one-off queries when cc-session doesn't cover your need:

# 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'

Session Insights

After running any analysis, always generate a "Session Insights" section with actionable recommendations. The tone should be friendly and mentoring - a helpful colleague who noticed some patterns, not a critic.

What to Look For

Scan the session data for these patterns and generate recommendations where relevant:

Tool usage improvements:

• Using Bash(grep ...) or Bash(cat ...) instead of Grep/Read tools - suggest the dedicated tools
• Repeated failed tool calls with same input - suggest pivoting earlier
• Heavy Bash usage for tasks a skill handles - recommend the skill by name
• No use of parallel tool calls when independent reads/searches could overlap

Workflow patterns:

• Long sessions with no commits - suggest incremental commits
• No /save at session end - remind about session continuity
• Repeated context re-reading (same files read 3+ times) - suggest keeping notes or using /save
• Large blocks of manual work that /iterate could automate - mention the loop pattern
• Debugging spirals (5+ attempts at same approach) - suggest the 3-attempt pivot rule

Skill and command awareness:

• Manual code review without /review - mention the skill
• Test writing without /testgen - mention the skill
• Complex reasoning without /atomise - mention it for hard problems
• Agent spawning for tasks a skill already handles - suggest the lighter-weight option

Session efficiency:

• Very long sessions (100+ tool calls) - suggest breaking into focused sessions
• High error rate (>30% of tool calls return errors) - note the pattern and suggest investigation
• Excessive file reads vs edits ratio (>10:1) - might indicate uncertainty, suggest planning first

Permission recommendations: This is high-value - permission prompts break flow and cost context. Scan the session for:

• Bash commands that were used successfully and repeatedly - these are candidates for Bash(<command>:*) allow rules
• Tool patterns that appeared frequently (WebFetch, WebSearch, specific MCP tools) - suggest adding to allow list
• Commands that failed with permission errors or were retried - likely blocked by missing permissions

Generate a ready-to-paste permissions.allow snippet for .claude/settings.local.json:

**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.

Only recommend commands that were actually used successfully - never suggest blanket Bash(*). But do encourage wildcard patterns where sensible - Bash(git:*) is better than listing Bash(git status), Bash(git add), Bash(git commit) separately. Common wildcard groups:

• Bash(git:*) - all git operations
• Bash(npm:*), Bash(pnpm:*), Bash(uv:*) - package managers
• Bash(pytest:*), Bash(jest:*) - test runners
• Bash(docker:*), Bash(cargo:*), Bash(go:*) - build/runtime tools
• mcp__server-name__* - all tools from an MCP server

Group recommendations by category for clarity. Reference /setperms for a full permissions setup if the list is long.

Output Format

## 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]**
- ...

Scale the number of recommendations to the session size. A quick 10-minute session might warrant 1-2 observations. A sprawling multi-hour session with 100+ tool calls could easily have 10-15 actionable insights. Match the depth of analysis to the depth of the session.

Only mention patterns that are clearly present in the data - don't guess or stretch. If the session was clean and efficient, say so: "This was a well-structured session - nothing jumps out as needing improvement."

Reference Files

File	Contents
scripts/cc-session	CLI tool - session analysis with 14 commands, JSON output, project filtering
references/session-analysis.md	Raw jq recipes for custom analysis beyond cc-session

See Also

• log-ops - General JSONL processing, two-stage pipelines, cross-file correlation
• data-processing - JSON/YAML/TOML processing with jq and yq