IMPORTANT DISTINCTION: This skill analyzes Claude Code session transcripts (what Claude saw and thought), NOT application/production logs (what code executed). For application logs, use the analyze-logs skill instead.

• "why did Claude do X?"
• "what was in the context window?"
• "analyze session" / "check session logs"
• "debug Claude behavior"
• "token usage investigation"
• "context window exhaustion"
• "track agent delegation"
• Any mention of

  .jsonl

  session files

1. Debugging decisions - "Why did Claude choose approach X?" → View context at decision point
2. Token analysis - "Where are tokens being used?" → Track cache creation vs cache read
3. Agent tracking - "How are agents being delegated?" → Follow sidechain messages
4. Context exhaustion - "Why did Claude lose context?" → See context window growth
5. Performance issues - "Why is Claude slow?" → Identify cache thrashing

• Context window content at any point in conversation
• Token usage breakdown (input, cache creation, cache read, output)
• Message chains (parent-child relationships)
• Agent delegation patterns (sidechain vs main thread)
• Context window growth over time
• Thinking blocks (Claude's internal reasoning)
• Tool calls with parameters and results

• This skill: Analyzes Claude's session transcripts → Shows "what Claude saw and thought"
• analyze-logs skill: Analyzes OpenTelemetry application logs → Shows "what code executed"
• Use both together for complete debugging

1. Locate session file - Find .jsonl file in ~/.claude/projects/
2. Choose analysis mode - List messages, view context at index, or view at UUID
3. Execute analysis - Run view_session_context.py with appropriate flags
4. Interpret results - Examine context window, token usage, and decision points
5. Report findings - Explain Claude's behavior with evidence from context

1. Check message count - How long was the session?
2. Identify MAIN vs SIDE - SIDE indicates agent delegation
3. Spot token patterns:
   • High Cache Create = New context being cached
   • High Cache Read = Good cache utilization
   • High Cache Create repeatedly = Cache thrashing
4. Find interesting points - Large output tokens, sudden cache creation, sidechains
5. Note message indices for deeper investigation

1. Review message chain - Understand conversation flow
2. Read THINKING blocks - See Claude's internal reasoning
3. Check TOOL calls - What tools were invoked and why
4. Examine token breakdown (input, cache creation, cache read, output)
5. Check total context size - Is it approaching 200k limit?

• Cache creation spike = Context changed significantly
• High cache read = Good utilization (cost effective)
• Low cache read = Cache misses (investigate why)
• Growing total context = Approaching 200k limit

1. Summary - Session length, main vs sidechain messages, total tokens
2. Key insights - What explains the behavior?
3. Specific examples - Quote relevant thinking blocks, tool calls
4. Context evidence - Show what Claude had access to
5. Suggested next steps - Additional investigation or fixes

Analyzed session abc123.jsonl (42 messages):

Key Findings:
1. Agent delegation at message 15 (→ unit-tester)
   - Context window at that point: 24,059 tokens
   - Thinking: "Need comprehensive test coverage for new service"
   - Agent had access to service implementation but not architectural context

2. Cache thrashing at messages 28-35
   - Cache creation spiked to 18k tokens each message
   - Context kept changing due to repeated file edits
   - Suggestion: Batch edits to reduce cache invalidation

3. Context exhaustion at message 40
   - Total context: 189,234 tokens (approaching 200k limit)
   - Claude started summarizing instead of quoting full code

To investigate further:
- View agent delegation context: --message-index 15
- Examine cache thrashing: --message-index 30

1. Start with List Mode - Always get the overview first to identify interesting points
2. Identify Patterns - Look for high cache creation (10k+ tokens), SIDE messages, large outputs
3. Use Message Index for Deep Dives - From list output, drill down to specific points
4. Follow Agent Delegation Chains - When you see [SIDE], trace back to parent in main thread
5. Track Token Usage - Good: high cache read (80%+), Bad: repeated cache creation (thrashing)
6. Compare Before/After - When debugging changes, analyze sessions before and after fix
7. Correlate with Code Execution Logs - Session logs show "what Claude thought", OpenTelemetry logs show "what code executed"
8. Save Important Sessions - Archive critical sessions to

   .claude/artifacts/

   for future reference

1. Find session file → List messages (

   --list

   )
2. Identify message where decision was made
3. View context at that point (

   --message-index N

   )
4. Read THINKING blocks to see reasoning
5. Explain: "Claude did X because context included Y but not Z"

1. List messages to see token breakdown
2. Identify spikes in cache_creation_input_tokens
3. View context at spike points
4. Determine what caused cache invalidation
5. Suggest optimizations (batch edits, cache earlier)

1. List messages to find sidechains ([SIDE])
2. View sidechain message context
3. Trace back to parent in main thread
4. Compare context available in main vs sidechain
5. Explain what agent could/couldn't see

1. List messages to track context growth
2. Identify where total context approaches 200k
3. View context at exhaustion point
4. Analyze what's consuming space
5. Suggest context optimization (new session, prune messages)

• analyze-logs - Combine session logs (what Claude thought) with execution logs (what code did)
• debug-test-failures - See what context was available when tests were written
• orchestrate-agents - Track actual delegation patterns vs expected
• check-progress-status - Understand how tasks were completed (decision points, delegations)

• references/reference.md - Technical depth:
  • Session file format specification (JSONL structure)
  • Data models and content block types
  • Parent-child chain reconstruction algorithm
  • Cache token types and pricing details
  • Performance characteristics and limits
  • Tool implementation details
  • Understanding output format (session structure, token breakdown, message chains)
  • Advanced usage patterns (session comparison, pattern detection, metrics)
  • Troubleshooting guide (common errors, solutions)
  • Complete command reference
• templates/response-template.md - Response formatting:
  • 6 response templates for different contexts
  • List mode summary template
  • Context window analysis template
  • Agent delegation investigation template
  • Token usage spike template
  • Context exhaustion template

• Python 3.12+ (already in project)
• Session viewer:

  .claude/tools/utils/view_session_context.py

  (bundled)
• jq (optional, for advanced analysis):

  brew install jq

• User-level:

  ~/.claude/projects/-Users-{username}-{project-path}/{session-uuid}.jsonl

• Generated automatically by Claude Code

undefined

python3 .claude/tools/utils/view_session_context.py <session.jsonl> --list

python3 .claude/tools/utils/view_session_context.py <session.jsonl> --message-index 10

python3 .claude/tools/utils/view_session_context.py <session.jsonl> --uuid "abc123..."

python3 .claude/tools/utils/view_session_context.py <session.jsonl> --message-index 10 --raw

ls -lt ~/.claude/projects/-Users-$(whoami)-*/*.jsonl | head -5

• This skill provides X-ray vision into Claude's decision-making
• Use when behavior is unexpected or token usage is unclear
• Complements OpenTelemetry logs (code execution) with context window visibility (what Claude thought)
• Essential for debugging complex agent orchestration
• Start with

  --list

  , then drill down with

  --message-index