History Insight

# Session File Format (.jsonl)

Claude Code 세션 파일의 상세 구조 및 파싱 방법

## JSONL Type 분류

| type | 설명 | 필요 여부 |
|------|------|---------|
| `user` | 사용자 메시지 | ✅ 필요 |
| `assistant` | Claude 응답 | ✅ 필요 (text만) |
| `file-history-snapshot` | 파일 백업 스냅샷 | ❌ 버림 |
| `queue-operation` | 큐 연산 로그 | ❌ 버림 |
| `system` | 시스템 메시지 | ⚪ 선택 |
| `summary` | 세션 요약 | ⚪ 선택 |

## 실제 분석 결과 (12MB 파일 예시)

| Type | Lines | Size | 비율 |
|------|-------|------|------|
| `file-history-snapshot` | 7,984 | 8.4MB | **67%** |
| `queue-operation` | 15,948 | 3.4MB | **27%** |
| `user` | 127 | 542KB | 4% |
| `assistant` | 163 | 255KB | 2% |
| `system` | 13 | 9KB | <1% |
| `summary` | 5 | 600B | <1% |

**결론:** 실제 대화는 6%, 나머지 94%는 메타데이터

## assistant 메시지 내부 구조

`.message.content[]` 배열 내부:

| 내부 type | 설명 | 필요 여부 |
|-----------|------|---------|
| `thinking` | Claude 생각 과정 + signature | ❌ 버림 |
| `tool_use` | tool 호출 정보 | ❌ 버림 |
| `text` | **실제 응답 텍스트** | ✅ 필요 |

## JSON 파싱 명령어

**user 메시지 추출:**
```bash
jq -c 'select(.type == "user") | {type, content: .message.content, ts: .timestamp}' <file.jsonl>
```

**assistant 메시지 추출 (text만):**
```bash
jq -c 'select(.type == "assistant") | {type, texts: [.message.content[] | select(.type == "text") | .text], ts: .timestamp}' <file.jsonl>
```

**한 번에 대화만 추출:**
```bash
jq -c '
  if .type == "user" then
    {type: "user", content: .message.content, ts: .timestamp}
  elif .type == "assistant" then
    {type: "assistant", texts: [.message.content[]? | select(.type == "text") | .text], ts: .timestamp}
    | select(.texts | length > 0)
  else empty end
' <file.jsonl>
```

**결과:** 12MB → ~160KB (99% 감소)


#!/bin/bash
# extract-session.sh
# Extract essential conversation from Claude Code session JSONL files
#
# Usage: ./extract-session.sh <session.jsonl>
# Output: Filtered JSON to stdout
#
# ============================================================
# 세션 파일 구조 분석 결과 (12MB 파일 예시)
# ============================================================
#
# JSONL type 분포:
#   file-history-snapshot : 67% (8.4MB) → 버림
#   queue-operation       : 27% (3.4MB) → 버림
#   user + assistant      :  6% (800KB) → 추출
#   system, summary       : <1%         → 선택적
#
# assistant.message.content[] 내부:
#   thinking  : Claude 생각 + signature → 버림
#   tool_use  : tool 호출 정보          → 버림
#   text      : 실제 응답 텍스트        → 추출
#
# 결과: 12MB → ~800KB (93% 감소)
# ============================================================

set -e

SESSION_FILE="$1"

if [ -z "$SESSION_FILE" ]; then
  echo "Usage: $0 <session.jsonl>" >&2
  exit 1
fi

if [ ! -f "$SESSION_FILE" ]; then
  echo "Error: File not found: $SESSION_FILE" >&2
  exit 1
fi

if ! command -v jq &> /dev/null; then
  echo "Error: jq is required. Install with: brew install jq" >&2
  exit 1
fi

# Extract conversation only:
# - summary: 세션 요약
# - user: 사용자 메시지 (.message.content)
# - assistant: Claude 응답 중 text만 (.message.content[].type == "text")
#
# Explicitly ignored (94% of file size):
# - file-history-snapshot: 파일 백업 스냅샷
# - queue-operation: 큐 연산 로그
# - assistant.thinking: 생각 과정 + signature
# - assistant.tool_use: tool 호출 정보

jq -c '
  if .type == "summary" then
    {type: "summary", summary: .summary}
  elif .type == "user" then
    {
      type: "user",
      content: .message.content,
      ts: .timestamp
    }
  elif .type == "assistant" then
    {
      type: "assistant",
      texts: [.message.content[]? | select(.type == "text") | .text],
      ts: .timestamp
    } | select(.texts | length > 0)
  else
    empty
  end
' "$SESSION_FILE" 2>/dev/null | jq -s '{
  file: "'"$SESSION_FILE"'",
  message_count: length,
  messages: .
}'


---
name: history-insight
description: This skill should be used when user wants to access, capture, or reference Claude Code session history. Trigger when user says "capture session", "save session history", or references past/current conversation as a source - whether for saving, extracting, summarizing, or reviewing. This includes any mention of "what we discussed", "today's work", "session history