session-replay

# Session Replay Skill

## Purpose

This skill analyzes claude-trace JSONL files to provide insights into Claude Code session health, token usage patterns, error frequencies, and agent effectiveness. It complements the `/transcripts` command by focusing on API-level trace data rather than conversation transcripts.

## When to Use This Skill

- **Session debugging**: Diagnose why a session was slow or failed
- **Token analysis**: Understand token consumption patterns
- **Error patterns**: Identify recurring failures across sessions
- **Performance optimization**: Find bottlenecks in tool usage
- **Agent effectiveness**: Measure which agents/tools are most productive

## Quick Start

### Analyze Latest Session

```
User: Analyze my latest session health
```

I'll analyze the most recent trace file:

```python
# Read latest trace file from .claude-trace/
trace_dir = Path(".claude-trace")
trace_files = sorted(trace_dir.glob("*.jsonl"), key=lambda f: f.stat().st_mtime)
latest = trace_files[-1] if trace_files else None

# Parse and analyze
if latest:
    analysis = analyze_trace_file(latest)
    print(format_session_report(analysis))
```

### Compare Multiple Sessions

```
User: Compare token usage across my last 5 sessions
```

I'll aggregate metrics across sessions:

```python
trace_files = sorted(Path(".claude-trace").glob("*.jsonl"))[-5:]
comparison = compare_sessions(trace_files)
print(format_comparison_table(comparison))
```

## Actions

### Action: `health`

Analyze session health metrics from a trace file.

**What to do:**

1. Read the trace file (JSONL format)
2. Extract API requests and responses
3. Calculate metrics:
   - Total tokens (input/output)
   - Request count and timing
   - Error rate
   - Tool usage distribution
4. Generate health report

**Metrics to extract:**

```python
# From each JSONL line containing a request/response pair:
{
    "timestamp": "...",
    "request": {
        "method": "POST",
        "url": "https://api.anthropic.com/v1/message