extracting-session-data

Extracting Session Data Skill

Core Responsibility

Provide raw access to Claude Code session logs stored in ~/.claude/projects/{project-dir}/{session-id}.jsonl.

Key Principle: This skill extracts data only - return raw data to calling skills for analysis. Do not analyze or interpret within this skill.

Available Scripts

All scripts located in scripts/ subdirectory relative to this skill.

1. locate-logs.sh

Find log directory or specific session file path.

# 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

Use when: Building dynamic paths, verifying logs exist before processing.

2. list-sessions.sh

Enumerate all sessions with metadata (ID, size, lines, date, branch).

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

Output formats: table, json, csv Sort options: date, size, lines

Use when: Starting retrospective, showing available sessions to user, checking for recent sessions.

3. extract-data.sh

Parse JSONL logs and extract specific data types.

Available extraction types:

• metadata - Session info (ID, timestamps, branch, working dir)
• user-prompts - All user messages
• tool-usage - Tool call statistics
• errors - Failed tool calls with timestamps
• thinking - Thinking blocks (if extended thinking enabled)
• text-responses - Assistant text responses only
• statistics - Session metrics (message counts, tool calls, errors)
• all - Combined extraction

Use when: Need specific data without loading entire log, generating metrics, identifying errors.

4. filter-sessions.sh

Find sessions matching criteria.

Filter options:

• --since DATE - Sessions modified since date ("2 days ago", "2025-10-20")
• --until DATE - Sessions modified until date
• --branch NAME - Sessions on specific git branch
• --min-size SIZE - Minimum file size ("1M", "500K")
• --max-size SIZE - Maximum file size
• --min-lines N - Minimum line count
• --max-lines N - Maximum line count
• --has-errors - Only sessions with failed tool calls
• --keyword WORD - Sessions containing keyword

Output formats: list, paths, json

Use when: User requests analysis of recent sessions, finding sessions for specific feature/branch, identifying problematic sessions.

Working Process

Single Session Analysis

Multiple Session Analysis

Integration Pattern for Calling Skills

When another skill (like retrospecting) needs session data:

1. Discovery: Use list-sessions.sh or filter-sessions.sh to find relevant sessions
2. Size Check: Use extract-data.sh --type statistics to determine session complexity
3. Targeted Extraction: Use extract-data.sh with specific types for needed data
4. Return Raw Data: Return extracted data to caller for analysis

Example:

Context Budget Management

CRITICAL: This skill is designed for context efficiency

Use Bash Processing, Not Read Tool

Check Session Size Before Loading

Never load full session logs into context without checking size first.

Return Raw Data to Caller

This skill should:

• Execute bash scripts to extract data
• Return raw text output to calling skill
• Let calling skill manage context for analysis
• Avoid interpretation or analysis within this skill

Output Format

Return raw extracted data with minimal formatting:

No analysis, no interpretation - just data extraction.

Error Handling

All scripts exit with non-zero status on errors and output to stderr.

Check exit status before processing:

Common error messages:

• 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

Path Calculation

Claude Code stores sessions using this pattern:

Where {project-identifier} is calculated by replacing all / with - in the absolute working directory path:

All scripts use locate-logs.sh internally for consistent path calculation.

Anti-Patterns to Avoid

Don't:

• Load full session logs into context without checking size
• Parse JSONL manually - use extract-data.sh
• Hardcode log paths - use locate-logs.sh
• Analyze or interpret data - return raw data to caller
• Process large logs synchronously without user awareness

Do:

• Check session size with --type statistics before processing
• Use appropriate extraction type for specific needs
• Filter sessions before extraction for efficiency
• Stream/pipe data when processing multiple sessions
• Return raw data for caller to analyze

Success Criteria

Effective use of this skill means:

1. Efficient Discovery: Quickly find relevant sessions without manual searching
2. Targeted Extraction: Get exactly the data needed, nothing more
3. Context Preservation: Avoid loading unnecessary data into context
4. Raw Data Focus: Return unprocessed data for caller to analyze
5. Multi-Session Support: Handle analysis across timeframes or branches efficiently

Dependencies

Required:

• bash (v4.0+)
• jq (JSON parser)

Scripts check for jq and provide installation instructions if missing: