history-insight

History Insight

Analyze Claude Code session history and extract insights.

---

Data Location

~/.claude/projects/<encoded-cwd>/*.jsonl

Path Encoding: /Users/foo/project → -Users-foo-project

Detailed file format: ${baseDir}/references/session-file-format.md

---

Execution Algorithm

Step 1: Ask Scope [MANDATORY]

Scope determination:

1. If specified (AskUserQuestion may be omitted):

   • "Current project only" / "this project" → current_project
   • "All sessions" / "all" → all_sessions

2. If not specified - Call AskUserQuestion:

   question: "세션 검색 범위를 선택하세요"
   options:
     - "현재 프로젝트만" → ~/.claude/projects/<encoded-cwd>/*.jsonl
     - "모든 Claude Code 세션" → ~/.claude/projects/**/*.jsonl
   

---

Step 2: Find Session Files

# Current project only
find ~/.claude/projects/<encoded-cwd> -name "*.jsonl" -type f

# All sessions (모든 프로젝트)
find ~/.claude/projects -name "*.jsonl" -type f

Date filtering: Check the file's mtime (modification time) and then filter. Per-OS stat options differ:

• macOS: stat -f "%Sm" -t "%Y-%m-%d" <file>
• Linux: stat -c "%y" <file>

---

Step 3: Process Sessions

Decision Tree

Session files found?
├─ No → Error: "No sessions found"
└─ Yes → How many files?
    ├─ 1-3 files → Direct Read + parse
    └─ 4+ files → Batch Extract Pipeline

1-3 Files

Parse JSONL by reading directly. If the file is large (≥5000 tokens), extract-session.sh use:

${baseDir}/scripts/extract-session.sh <session.jsonl>

4+ Files: Batch Extract Pipeline

1. Create cache directory (/tmp/cc-cache/<analysis-name>/)
2. Save session list (sessions.txt)
3. Extract messages in bulk with jq (user_messages.txt)
4. Cleanup and filtering (clean_messages.txt)
5. Comprehensive analysis with Task(opus)

When the file is too large: parallel batch analysis

clean_messages.txtWhen it is too large and Read fails:

1. Split the file:

   split -l 2000 clean_messages.txt /tmp/cc-cache/<name>/batch_
   

2. Call parallel Task(opus):

   Task(subagent_type="general-purpose", model="opus", run_in_background=true)
   prompt: "batch_XX 파일을 읽고 주제/패턴 요약해줘"
   

3. Merge results: Comprehensive with Task(opus)

---

Step 4: Report Results

## Session Capture Complete

- **Sessions:** N files processed
- **Messages:** X total, Y after filter

### Extracted Insights
[분석 결과]

---

Error Handling

Scenario	Response
No session files found	"No session files found for this project."
File too large	Auto-preprocess with extract-session.sh
jq not installed	"Error: jq is required. Install with: brew install jq"
Task failed	"Warning: Could not process [file]. Skipping."
0 relevant sessions	"No sessions matched your criteria."

---

Security Notes

• Do not expose full paths in output (~ use prefix)

---

Related Resources

• ${baseDir}/scripts/extract-session.sh - JSONL compression (remove thinking, tool_use)
• ${baseDir}/references/session-file-format.md - JSONL structure and parsing