session-replay

セッションリプレイのスキル

目的

このスキルは、claude-trace の JSONL ファイルを分析し、Claude Code セッションの健全性、トークン使用パターン、エラーの発生頻度、エージェントの有効性に関するインサイトを提供します。会話のトランスクリプトではなく API レベルのトレースデータに焦点を当てることで、/transcripts コマンドを補完します。

このスキルを使用する場面

• セッションのデバッグ：セッションが遅かった、または失敗した理由を診断します
• トークン分析：トークン消費パターンを把握します
• エラーパターン：セッション全体で繰り返し発生する失敗を特定します
• パフォーマンスの最適化：ツール使用時のボトルネックを見つけます
• エージェントの有効性：最も生産性の高いエージェント／ツールを測定します

クイックスタート

最新のセッションを分析する

User: Analyze my latest session health

最新のトレースファイルを分析します：

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

複数のセッションを比較する

User: Compare token usage across my last 5 sessions

セッション全体のメトリクスを集計します：

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

アクション

アクション：health

トレースファイルからセッションの健全性メトリクスを分析します。

実行内容：

1. トレースファイルを読み込みます（JSONL 形式）
2. API リクエストとレスポンスを抽出します
3. 次のメトリクスを計算します：
   • トークンの合計（入力／出力）
   • リクエスト数とタイミング
   • エラー率
   • ツール使用の分布
4. 健全性レポートを生成します

抽出するメトリクス：

# From each JSONL line containing a request/response pair:
{
    "timestamp": "...",
    "request": {
        "method": "POST",
        "url": "https://api.anthropic.com/v1/messages",
        "body": {
            "model": "claude-...",
            "messages": [...],
            "tools": [...]
        }
    },
    "response": {
        "usage": {
            "input_tokens": N,
            "output_tokens": N
        },
        "content": [...],
        "stop_reason": "..."
    }
}

出力形式：

Session Health Report
=====================
File: log-2025-11-23-19-32-36.jsonl
Duration: 45 minutes

Token Usage:
- Input: 125,432 tokens
- Output: 34,521 tokens
- Total: 159,953 tokens
- Efficiency: 27.5% output ratio

Request Stats:
- Total requests: 23
- Average latency: 2.3s
- Errors: 2 (8.7%)

Tool Usage:
- Read: 45 calls
- Edit: 12 calls
- Bash: 8 calls
- Grep: 15 calls

Health Score: 82/100 (Good)
- Minor issue: 2 errors detected

アクション：errors

セッション全体でエラーパターンを特定します。

実行内容：

1. トレースファイルをスキャンしてエラーレスポンスを探します
2. エラーを種類別に分類します
3. 繰り返し発生するパターンを特定します
4. 修正方法を提案します

検出するエラーカテゴリ：

• レート制限エラー（429）
• トークン上限超過
• ツール実行の失敗
• タイムアウトエラー
• API エラー

出力形式：

Error Analysis
==============
Sessions analyzed: 5
Total errors: 12

Error Categories:
1. Rate limit (429): 5 occurrences
   - Recommendation: Add delays between requests

2. Token limit: 3 occurrences
   - Recommendation: Use context management skill

3. Tool failures: 4 occurrences
   - Bash timeout: 2
   - File not found: 2
   - Recommendation: Check paths before operations

アクション：compare

複数のセッションのメトリクスを比較します。

実行内容：

1. 複数のトレースファイルを読み込みます
2. 比較可能なメトリクスを抽出します
3. 傾向を計算します
4. 異常を特定します

出力形式：

Session Comparison
==================
                    Session 1   Session 2   Session 3   Trend
Tokens (total)      150K        180K        120K        -17%
Requests            25          30          18          -28%
Errors              2           0           1           stable
Duration (min)      45          60          30          -33%
Efficiency          0.27        0.32        0.35        +7%

アクション：tools

ツールの使用パターンを分析します。

実行内容：

1. トレースからツール呼び出しを抽出します
2. 頻度とタイミングを計算します
3. 非効率なパターンを特定します
4. 最適化方法を提案します

検出するパターン：

• 並列実行できる逐次呼び出し
• 同じファイルの繰り返し読み込み
• 過剰な grep／glob 呼び出し
• 使用されていないツールの結果

出力形式：

Tool Usage Analysis
===================
Tool          Calls   Avg Time   Success Rate
Read          45      0.1s       100%
Edit          12      0.3s       92%
Bash          8       1.2s       75%
Grep          15      0.2s       100%
Task          3       45s        100%

Optimization Opportunities:
1. 5 Read calls to same file within 2 minutes
   - Consider caching strategy

2. 3 sequential Bash calls could be parallelized
   - Use multiple Bash calls in single message

実装上の注意

JSONL トレースの解析

Claude-trace ファイルは、リクエストとレスポンスのペアを含む JSONL 形式です：

import json
from pathlib import Path
from typing import Dict, List, Any

def parse_trace_file(path: Path) -> List[Dict[str, Any]]:
    """Parse a claude-trace JSONL file."""
    entries = []
    with open(path) as f:
        for line in f:
            if line.strip():
                try:
                    entry = json.loads(line)
                    entries.append(entry)
                except json.JSONDecodeError:
                    continue
    return entries

def extract_metrics(entries: List[Dict]) -> Dict[str, Any]:
    """Extract session metrics from trace entries."""
    metrics = {
        "total_input_tokens": 0,
        "total_output_tokens": 0,
        "request_count": 0,
        "error_count": 0,
        "tool_usage": {},
        "timestamps": [],
    }

    for entry in entries:
        if "request" in entry:
            metrics["request_count"] += 1
            metrics["timestamps"].append(entry.get("timestamp", 0))

        if "response" in entry:
            usage = entry["response"].get("usage", {})
            metrics["total_input_tokens"] += usage.get("input_tokens", 0)
            metrics["total_output_tokens"] += usage.get("output_tokens", 0)

            # Check for errors
            if entry["response"].get("error"):
                metrics["error_count"] += 1

        # Extract tool usage from request body
        if "request" in entry and "body" in entry["request"]:
            body = entry["request"]["body"]
            if isinstance(body, dict) and "tools" in body:
                for tool in body["tools"]:
                    name = tool.get("name", "unknown")
                    metrics["tool_usage"][name] = metrics["tool_usage"].get(name, 0) + 1

    return metrics

トレースファイルの場所

def find_trace_files(trace_dir: str = ".claude-trace") -> List[Path]:
    """Find all trace files, sorted by modification time."""
    trace_path = Path(trace_dir)
    if not trace_path.exists():
        return []
    return sorted(
        trace_path.glob("*.jsonl"),
        key=lambda f: f.stat().st_mtime,
        reverse=True  # Most recent first
    )

エラー処理

一般的なエラー状況を適切に処理します：

def safe_parse_trace_file(path: Path) -> Tuple[List[Dict], List[str]]:
    """Parse trace file with error collection for malformed lines.

    Returns:
        Tuple of (valid_entries, error_messages)
    """
    entries = []
    errors = []

    if not path.exists():
        return [], [f"Trace file not found: {path}"]

    try:
        with open(path) as f:
            for line_num, line in enumerate(f, 1):
                if not line.strip():
                    continue
                try:
                    entry = json.loads(line)
                    entries.append(entry)
                except json.JSONDecodeError as e:
                    errors.append(f"Line {line_num}: Invalid JSON - {e}")
    except PermissionError:
        return [], [f"Permission denied: {path}"]
    except UnicodeDecodeError:
        return [], [f"Encoding error: {path} (expected UTF-8)"]

    return entries, errors


def format_error_report(errors: List[str], path: Path) -> str:
    """Format error report for user display."""
    if not errors:
        return ""

    report = f"""
Trace File Issues
=================
File: {path.name}
Issues found: {len(errors)}

"""
    for error in errors[:10]:  # Limit to first 10
        report += f"- {error}\n"

    if len(errors) > 10:
        report += f"\n... and {len(errors) - 10} more issues"

    return report

一般的なエラー状況：

状況	原因	対処
空のファイル	セッションに API 呼び出しがありません	「分析するデータがありません」と報告します
不正な JSON	トレースの破損、または書き込みの中断	行をスキップし、エラーレポートに件数を記録します
フィールドの欠落	古いトレース形式	デフォルト値を指定して .get() を使用します
アクセス拒否	別のプロセスがファイルをロックしています	明確なエラーメッセージを表示し、再試行を提案します
エンコーディングエラー	UTF-8 以外の文字	エンコーディングの問題を報告します

既存のツールとの統合

ツール選択マトリクス

ニーズ	使用するもの	理由
「セッションが遅かったのはなぜですか？」	session-replay	API のレイテンシとトークンのメトリクス
「前回のセッションでは何を話しましたか？」	/transcripts	会話の内容
「セッションから学びを抽出する」	CodexTranscriptsBuilder	ナレッジの抽出
「トークン使用量を削減する」	session-replay + context_management	メトリクス + 最適化
「中断した作業を再開する」	/transcripts	コンテキストの復元

/transcripts コマンドとの比較

/transcripts（会話管理）：

• 会話の内容に焦点を当てます
• セッションのコンテキストを復元します
• コンテキストの保持に使用します
• トリガー：「セッションを復元」「作業を続ける」「何をしていたか」

session-replay スキル（API レベルの分析）：

• API のメトリクスに焦点を当てます
• パフォーマンスとエラーを分析します
• デバッグと最適化に使用します
• トリガー：「セッションの状態」「トークン使用量」「遅い理由」「セッションをデバッグ」

CodexTranscriptsBuilder との比較

CodexTranscriptsBuilder（ナレッジの抽出）：

• 会話からパターンを抽出します
• 学習コーパスを構築します
• ナレッジを重視します
• トリガー：「パターンを抽出」「ナレッジベースを構築」「セッションから学ぶ」

session-replay スキル（メトリクス分析）：

• パフォーマンスメトリクスを抽出します
• 技術的な問題を特定します
• 運用を重視します
• トリガー：「パフォーマンスメトリクス」「エラーパターン」「ツールの効率」

組み合わせたワークフロー

ワークフロー 1：トークンの問題を診断して解決する

1. session-replay: Analyze token usage patterns (health action)
2. Identify high-token operations
3. context_management skill: Apply proactive trimming
4. session-replay: Compare before/after sessions (compare action)

ワークフロー 2：インシデント発生後の分析

1. session-replay: Identify error patterns (errors action)
2. /transcripts: Review conversation context around errors
3. session-replay: Check tool usage around failures (tools action)
4. Document findings in DISCOVERIES.md

ワークフロー 3：パフォーマンスのベースライン

1. session-replay: Analyze 5-10 recent sessions (compare action)
2. Establish baseline metrics (tokens, latency, errors)
3. Track deviations from baseline over time

ストレージの場所

• トレースファイル：.claude-trace/*.jsonl
• セッションログ：~/.amplihack/.claude/runtime/logs/<session_id>/
• 生成されたレポート：直接出力（永続ストレージは不要）

哲学との整合性

徹底したシンプルさ

• 単一の目的：トレースファイルのみを分析します。セッション管理やトランスクリプト編集は行いません
• 外部依存なし：Python の標準ライブラリ（json、pathlib、datetime）のみを使用します
• ファイルを直接解析：ORM、データベース、複雑な抽象化はありません
• 現在に焦点を当てる：現時点の内容を分析し、将来への備えはしません

ごまかしのない実装

• すべての関数が完全に動作：このスキルのすべてのコード例は、変更なしで実行できます
• 実際の解析とメトリクス：モックデータや仮の計算はありません
• スタブやプレースホルダーなし：文書に記載された機能はすべて動作します
• エラー時は速やかに失敗：明確なエラーメッセージを表示し、エラーを黙って無視しません

ブリックの哲学

• 自己完結型の分析：すべての機能をこの単一のスキルに含めています
• 明確な入力（トレースファイル）と出力（レポート）：隠れた状態や副作用はありません
• この仕様から再生成可能：この SKILL.md が完全な信頼できる情報源です
• 責務を分離：セッション分析のみを行い、ファイルを変更したりアクションを実行したりしません

制限事項

このスキルでは、以下のことはできません。

• トレースファイルの変更：読み取り専用の分析です。編集や削除はできません
• トレースの生成：claude-trace npm パッケージを使用してトレースファイルを作成してください
• セッションの復元：セッションを復元するには /transcripts コマンドを使用してください
• リアルタイム監視：完了したセッションを分析します。ライブ追跡はできません
• プロジェクト横断の分析：現在のプロジェクト内のトレースのみを分析します
• JSONL 以外の形式の解析：claude-trace の JSONL 形式のみをサポートします
• リモートトレースへのアクセス：ローカルファイルシステムのみを対象とし、クラウドストレージにはアクセスできません

効果的な分析のためのヒント

1. まずヘルスチェックを実行する：最初に health アクションを実行します
2. パターンを探す：errors を使って繰り返し発生する問題を見つけます
3. ホットスポットを最適化する：tools を使って非効率な箇所を見つけます
4. 傾向を追跡する：セッション間で compare を使います
5. トランスクリプトと組み合わせる：状況を把握するには /transcripts を使います

よくあるパターン

パターン 1：遅いセッションをデバッグする

User: My last session was really slow, analyze it

1. Run health action on latest trace
2. Check request latencies
3. Identify tool bottlenecks
4. Report findings with recommendations

パターン 2：トークン使用量を減らす

User: I'm hitting token limits, help me understand usage

1. Compare token usage across sessions
2. Identify high-token operations
3. Suggest context management strategies
4. Recommend workflow optimizations

パターン 3：繰り返し発生するエラーを修正する

User: I keep getting errors, find the pattern

1. Run errors action across last 10 sessions
2. Categorize and count error types
3. Identify root causes
4. Provide targeted fixes

リソース

• トレースディレクトリ：.claude-trace/
• トランスクリプトコマンド：/transcripts
• コンテキスト管理スキル：context-management
• 理念：~/.amplihack/.claude/context/PHILOSOPHY.md

トラブルシューティング

トレースファイルが見つからない

症状：「.claude-trace/ にトレースファイルがありません」

原因と対処法：

1. claude-trace が有効になっていない：セッションを開始する前に AMPLIHACK_USE_TRACE=1 を設定します
2. ディレクトリが間違っている：.claude-trace/ ディレクトリがあるプロジェクトのルートにいることを確認します
3. 新しいプロジェクトである：まずトレースを有効にしてセッションを実行します

メトリクスが不完全

症状：トークン数がない、または値がゼロになっている

原因と対処法：

1. セッションが中断された：セッションがクラッシュした場合、トレースが不完全になっている可能性があります
2. ストリーミング応答：一部のストリーミングモードでは、すべてのメトリクスが記録されないことがあります
3. 古いトレース形式：claude-trace を最新バージョンにアップグレードします

ヘルススコアが正しくないように見える

症状：スコアがセッションの実感と一致しない

スコアの見方：

• 90-100：優秀 — エラーが少なく、効率が良好です
• 70-89：良好 — 軽微な問題が検出されています
• 50-69：普通 — 調査する価値のある重大な問題があります
• 50 未満：不良 — エラーまたは非効率な箇所がある可能性が高いです

ヘルススコアの要因：

• エラー率（40% の重み）
• トークン効率比（30% の重み）
• リクエスト成功率（20% の重み）
• ツール成功率（10% の重み）

トレースファイルが大きい

症状：分析が遅い、またはメモリを大量に消費する

解決策：

1. ファイル全体ではなく、特定の時間範囲を分析します
2. 対象を絞って分析するには tools アクションを使います
3. 古いトレースをアーカイブします：mv .claude-trace/old-*.jsonl .claude-trace/archive/

覚えておくこと

このスキルは、セッション単位のデバッグと最適化に関する洞察を提供します。トランスクリプト管理を API レベルの可視性で補完します。問題の診断、ワークフローの最適化、Claude Code の動作パターンの把握に活用してください。

要点：トレースファイルには、セッションのパフォーマンスに関する生の情報が含まれています。このスキルは、そのデータから実行可能な洞察を引き出します。