Session Analyzer Skill

Discovers and analyzes Claude Code session transcripts from .claude/logs/ directory to help users understand their development workflow and identify optimization opportunities.

When to Use This Skill

Claude should invoke this skill when the user:

Wants to see available Claude Code sessions
Asks about recent development sessions or workflow history
Mentions analyzing workflow patterns or efficiency
Needs to find transcripts from a specific date
Wants to understand subagent usage across sessions
Requests session discovery or listing

Current Status

Implemented Features:

✅ Auto-discovery of session logs from .claude/logs/
✅ Date-based session listing and filtering
✅ Session grouping (main + subagent transcripts)
✅ Timeline display with start times
✅ Colored terminal output
✅ Date validation and formatting

Planned Features (not yet implemented):

🚧 Transcript parsing and correlation
🚧 Workflow analysis (task decomposition, handoffs, bottlenecks)
🚧 Metrics extraction (duration, success rate, tool usage)
🚧 Subagent orchestration evaluation
🚧 Code quality assessment
🚧 Recommendation generation
🚧 Report export (markdown format)

Key Capabilities

Session Discovery

Automatically scans .claude/logs/ directory for session transcripts
Identifies and groups related main and subagent transcripts
Sorts sessions chronologically (newest first)
Displays human-readable date formatting

Session Information

For each session, displays:

Session ID: Short identifier (first 8 chars of UUID)
Start Time: Precise timestamp (HH:MM:SS)
Main Transcript: Filename of primary session
Subagent Count: Number of related subagent transcripts

Date Filtering

Filter sessions by specific date (YYYYMMDD format)
View all sessions from a particular day
Navigate through session history by date

Usage Examples

List All Available Sessions

# Shows all dates with available sessions
node .claude/skills/session-analyzer/analyze-session.js

Output:

Available Claude Code session logs:

  1. October 17, 2025 (20251017)
  2. October 12, 2025 (20251012)
  3. October 7, 2025 (20251007)

Run with date to analyze:
  node analyze-session.js 20251017

List Sessions for Specific Date

# Shows all sessions from October 17, 2025
node .claude/skills/session-analyzer/analyze-session.js 20251017

Output:

Sessions for October 17, 2025:

  1. Session abc123de
     Time: 14:32:15
     Main: transcript_abc123de_20251017_143215.json
     Subagents: 8

  2. Session def456gh
     Time: 09:15:42
     Main: transcript_def456gh_20251017_091542.json
     Subagents: 3

Run with session ID to analyze:
  node analyze-session.js 20251017 abc123de

Analyze Specific Session

# Analyzes session abc123de from October 17, 2025
node .claude/skills/session-analyzer/analyze-session.js 20251017 abc123de

Output (current implementation shows basic info, detailed analysis coming):

Analyzing session: abc123de
Date: October 17, 2025
Main transcript: transcript_abc123de_20251017_143215.json
Subagent transcripts: 8

Subagent transcripts:
  - transcript_subagent_backend_abc123de_20251017_143220.json
  - transcript_subagent_frontend_abc123de_20251017_143245.json
  ...

Analysis complete! (Implementation pending)

Next steps:
  - Add transcript parsing logic
  - Implement workflow analysis
  - Generate metrics and recommendations

Transcript File Patterns

The script recognizes these filename patterns:

Main transcripts: transcript_<sessionId>_<YYYYMMDD>_<HHMMSS>.json
Subagent transcripts: transcript_subagent_<sessionId>_<YYYYMMDD>_<HHMMSS>.json

Session grouping is based on the session ID portion of the filename.

Common Use Cases

Session Discovery: "What sessions do I have from this week?"
- Use without arguments to list all dates
- Then specify date to see sessions
Recent Activity Review: "Show me today's Claude sessions"
- Use with today's date in YYYYMMDD format
Workflow Analysis Prep: "Find the session where I built the API"
- List sessions by date, identify by timestamp
Subagent Usage Tracking: "How many subagents did I use yesterday?"
- View session list with subagent counts

Tips for Claude

Default logs directory is .claude/logs/ in the current project
Date format must be YYYYMMDD (e.g., 20251017)
Session IDs are displayed as short 8-character identifiers (first part of UUID)
When user asks about "recent sessions", show the most recent date's sessions
Suggest running the transcript-condenser skill on specific sessions for detailed analysis
If logs directory doesn't exist, inform user that logging may not be enabled

Command Reference

node .claude/skills/session-analyzer/analyze-session.js [date] [sessionId]

Arguments:
  date       (optional) Session date in YYYYMMDD format (e.g., 20251017)
  sessionId  (optional) Short session ID to analyze (requires date)

Options:
  --help, -h  Show help message

Examples:
  node analyze-session.js                  # List all available session dates
  node analyze-session.js 20251017         # List sessions from Oct 17, 2025
  node analyze-session.js 20251017 abc123  # Analyze specific session

Integration with Other Skills

Workflow recommendation: After discovering sessions with this skill, use the transcript-condenser skill to generate detailed reports:

# 1. Find sessions
node .claude/skills/session-analyzer/analyze-session.js 20251017

# 2. Condense specific session
node .claude/skills/transcript-condenser/condense-transcript.js \
  .claude/logs/20251017/transcript_abc123de_20251017_143215.json \
  --output=session-report.md

Development Roadmap

Future enhancements will add:

Transcript Parsing: Load and parse JSON session data
Correlation Engine: Link subagent transcripts to main session events
Workflow Metrics: Calculate efficiency metrics, tool usage patterns
Bottleneck Detection: Identify slow operations and optimization opportunities
Quality Scoring: Evaluate code quality and testing coverage
Actionable Recommendations: Generate specific improvement suggestions
Report Generation: Export findings as markdown reports

Requirements

Node.js 18.0.0 or higher
No external dependencies (uses built-in Node.js modules only)
Requires .claude/logs/ directory with session transcripts