extracting-session-data

セッションデータ抽出スキル

主な役割

~/.claude/projects/{project-dir}/{session-id}.jsonl に保存されている Claude Code のセッションログへの生データアクセスを提供します。

重要な原則：このスキルはデータの抽出のみを行います。分析用に生データを呼び出し元のスキルに返してください。このスキル内で分析や解釈を行わないでください。

利用可能なスクリプト

すべてのスクリプトは、このスキルの scripts/ サブディレクトリにあります。

1. locate-logs.sh

ログディレクトリまたは特定のセッションファイルのパスを見つけます。

# Get logs directory for current working directory
scripts/locate-logs.sh

# Get logs directory for specific project
scripts/locate-logs.sh /path/to/project

# Get specific session log file path
scripts/locate-logs.sh /path/to/project abc123-session-id

使用する場面：動的なパスを作成するときや、処理前にログが存在することを確認するとき。

2. list-sessions.sh

メタデータ（ID、サイズ、行数、日付、ブランチ）とともにすべてのセッションを列挙します。

# List all sessions (table format)
scripts/list-sessions.sh

# JSON output
scripts/list-sessions.sh --format json

# Sort by size or lines
scripts/list-sessions.sh --sort size
scripts/list-sessions.sh --sort lines

# Specific project
scripts/list-sessions.sh /path/to/project

出力形式：table、json、csv 並べ替えオプション：date、size、lines

使用する場面：振り返りを始めるとき、ユーザーに利用可能なセッションを表示するとき、最近のセッションを確認するとき。

3. extract-data.sh

JSONL ログを解析し、指定した種類のデータを抽出します。

利用可能な抽出タイプ：

• metadata - セッション情報（ID、タイムスタンプ、ブランチ、作業ディレクトリ）
• user-prompts - すべてのユーザーメッセージ
• tool-usage - ツール呼び出しの統計
• errors - タイムスタンプ付きの失敗したツール呼び出し
• thinking - 思考ブロック（拡張思考が有効な場合）
• text-responses - アシスタントのテキスト応答のみ
• statistics - セッションの指標（メッセージ数、ツール呼び出し数、エラー数）
• all - すべてをまとめて抽出

# Extract from specific session
scripts/extract-data.sh --type statistics --session SESSION_ID
scripts/extract-data.sh --type errors --session SESSION_ID
scripts/extract-data.sh --type tool-usage --session SESSION_ID

# Extract from all sessions (omit --session)
scripts/extract-data.sh --type statistics

# Limit output
scripts/extract-data.sh --type user-prompts --limit 10

# Different project
scripts/extract-data.sh --type metadata --project /path/to/project

使用する場面：ログ全体を読み込まずに特定のデータが必要なとき、指標を生成するとき、エラーを特定するとき。

4. filter-sessions.sh

条件に一致するセッションを検索します。

フィルターオプション：

• --since DATE - 指定した日付以降に更新されたセッション（"2 days ago"、"2025-10-20"）
• --until DATE - 指定した日付までに更新されたセッション
• --branch NAME - 特定の Git ブランチ上のセッション
• --min-size SIZE - 最小ファイルサイズ（"1M"、"500K"）
• --max-size SIZE - 最大ファイルサイズ
• --min-lines N - 最小行数
• --max-lines N - 最大行数
• --has-errors - ツール呼び出しに失敗したセッションのみ
• --keyword WORD - 指定したキーワードを含むセッション

出力形式：list、paths、json

# Recent sessions
scripts/filter-sessions.sh --since "2 days ago"

# Large sessions with errors
scripts/filter-sessions.sh --min-lines 500 --has-errors

# Sessions on main branch in last week
scripts/filter-sessions.sh --branch main --since "7 days ago"

# Sessions containing keyword
scripts/filter-sessions.sh --keyword "authentication"

# Get paths only (for piping)
scripts/filter-sessions.sh --since "1 day ago" --format paths

使用する場面：ユーザーから最近のセッションの分析を求められたとき、特定の機能やブランチに関するセッションを見つけるとき、問題のあるセッションを特定するとき。

作業プロセス

単一セッションの分析

# 1. Verify session exists and get metadata
scripts/extract-data.sh --type metadata --session SESSION_ID

# 2. Get session statistics (to determine size)
scripts/extract-data.sh --type statistics --session SESSION_ID

# 3. Extract specific data as needed
scripts/extract-data.sh --type errors --session SESSION_ID
scripts/extract-data.sh --type tool-usage --session SESSION_ID

複数セッションの分析

# 1. Filter to find relevant sessions
scripts/filter-sessions.sh --since "7 days ago" --branch main

# 2. Extract data from all filtered sessions
scripts/extract-data.sh --type statistics

# 3. Or iterate through filtered subset
SESSIONS=$(scripts/filter-sessions.sh --has-errors --format paths)
for session in $SESSIONS; do
    SESSION_ID=$(basename "$session" .jsonl)
    scripts/extract-data.sh --type errors --session $SESSION_ID
done

呼び出し元スキルとの連携パターン

別のスキル（振り返りを行うスキルなど）がセッションデータを必要とする場合：

1. 検出：list-sessions.sh または filter-sessions.sh を使って関連するセッションを見つけます
2. サイズの確認：extract-data.sh --type statistics を使ってセッションの複雑さを判断します
3. 対象を絞った抽出：必要なデータの種類を指定して extract-data.sh を使います
4. 生データを返す：抽出したデータを分析用に呼び出し元へ返します

例：

# Get latest session ID
LATEST=$(scripts/list-sessions.sh --format json --sort date | jq -r '.[0].sessionId')

# Check size before processing
STATS=$(scripts/extract-data.sh --type statistics --session $LATEST)
LINE_COUNT=$(echo "$STATS" | grep "Total Lines:" | awk '{print $3}')

# Extract based on size
if [ "$LINE_COUNT" -lt 500 ]; then
    # Small session: extract detail
    scripts/extract-data.sh --type errors --session $LATEST
    scripts/extract-data.sh --type tool-usage --session $LATEST
else
    # Large session: summary only
    scripts/extract-data.sh --type statistics --session $LATEST
fi

コンテキスト予算の管理

重要：このスキルはコンテキストを効率的に使うよう設計されています

Read ツールではなく Bash 処理を使う

# GOOD: Extract via bash, stays in bash context
STATS=$(scripts/extract-data.sh --type statistics)
# Process $STATS in bash

# BAD: Reading full log files
Read ~/.claude/projects/-path/session.jsonl
# Loads entire file into context unnecessarily

読み込む前にセッションサイズを確認する

最初にサイズを確認せず、セッションログ全体をコンテキストに読み込まないでください。

# Always check statistics first
scripts/extract-data.sh --type statistics --session SESSION_ID
# Shows total lines, message counts, etc.

# Decision rules:
# - Small (<500 lines): Can extract detail safely
# - Medium (500-2000 lines): Use selective extraction
# - Large (>2000 lines): Statistics only, offer targeted deep-dives

生データを呼び出し元に返す

このスキルでは、以下を行います。

• Bash スクリプトを実行してデータを抽出する
• 生のテキスト出力を呼び出し元のスキルに返す
• 呼び出し元のスキルに分析用のコンテキスト管理を任せる
• このスキル内での解釈や分析を避ける

出力形式

書式設定を最小限にして、抽出した生データを返します。

# Statistics output
Session: abc123-def456-ghi789
  Total Lines: 450
  User Messages: 12
  Assistant Messages: 23
  Tool Calls: 45
  Errors: 2

# Tool usage output
=== Tool Usage: abc123-def456-ghi789 ===
Read                          15
Bash                          12
Edit                          8
Grep                          5
Write                         3

分析や解釈は行わず、データの抽出のみを行います。

エラー処理

すべてのスクリプトは、エラー時にゼロ以外のステータスで終了し、stderr に出力します。

処理前に終了ステータスを確認してください。

if ! scripts/locate-logs.sh /path/to/project &>/dev/null; then
    # Handle: logs directory doesn't exist
    echo "Project has no session logs yet"
fi

if ! scripts/extract-data.sh --type metadata --session abc123 &>/dev/null; then
    # Handle: session doesn't exist
    echo "Session not found"
fi

一般的なエラーメッセージ：

• Error: Logs directory not found: ~/.claude/projects/-path
• Error: Session file not found: ~/.claude/projects/-path/session-id.jsonl
• Error: --type is required
• Error: jq is required but not installed. Install with: brew install jq

パスの計算

Claude Code は、次のパターンでセッションを保存します。

~/.claude/projects/{project-identifier}/{session-id}.jsonl

{project-identifier} は、絶対作業ディレクトリのパスに含まれるすべての / を - に置き換えて計算します。

# Example: /Users/user/project → -Users-user-project
PROJECT_ID=$(echo "${PWD}" | sed 's/\//\-/g')
LOGS_DIR="${HOME}/.claude/projects/${PROJECT_ID}"

すべてのスクリプトは、一貫したパス計算のために内部で locate-logs.sh を使用します。

避けるべきアンチパターン

避けてください：

• サイズを確認せずにセッションログ全体をコンテキストに読み込む
• JSONL を手動で解析する — extract-data.sh を使用してください
• ログパスをハードコードする — locate-logs.sh を使用してください
• データを分析または解釈する — 呼び出し元に生データを返してください
• ユーザーに知らせずに大きなログを同期的に処理する

推奨事項：

• 処理前に --type statistics でセッションサイズを確認する
• 目的に適した抽出タイプを使用する
• 効率化のため、抽出前にセッションをフィルタリングする
• 複数のセッションを処理する際は、データをストリーミングまたはパイプで渡す
• 呼び出し元が分析できるよう、生データを返す

成功基準

このスキルを効果的に使用できている状態とは、次のとおりです。

1. 効率的な検索：手動で検索することなく、関連するセッションをすばやく見つける
2. 的を絞った抽出：必要なデータだけを過不足なく取得する
3. コンテキストの保持：不要なデータをコンテキストに読み込まない
4. 生データの重視：呼び出し元が分析できるよう、未処理のデータを返す
5. 複数セッションへの対応：期間やブランチをまたいだ分析を効率的に処理する

依存関係

必須：

• bash（v4.0+）
• jq（JSON パーサー）

スクリプトは jq の有無を確認し、見つからない場合はインストール手順を表示します。

Error: jq is required but not installed. Install with: brew install jq