README

This skill provides programmatic access to Claude Code’s native session logs stored in:

It can:

• Locate session log directories and files
• List available sessions with metadata (size, date, branch)
• Extract specific data (errors, tool usage, messages, statistics)
• Filter sessions by criteria (timeframe, branch, errors, keywords)

When to Use

You typically won’t invoke this skill directly. Other skills (like retrospecting) use it behind the scenes to access session data efficiently.

However, you might invoke it directly when you want to:

• See what sessions are available
• Find sessions from a specific timeframe or branch
• Extract specific data (like all errors from recent sessions)
• Check session sizes before analysis

Example Invocations

What to Expect

Process Flow

When you request session data, the skill will:

1. Locate your project’s session logs directory
2. Filter or list sessions based on your criteria
3. Extract the requested data type
4. Return raw data for analysis or presentation

Output Format

This skill returns raw data rather than analyzed insights:

Other skills (like retrospecting) interpret this data to generate insights.

Available Operations

1. List Sessions

See all available sessions for your project:

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

2. Filter Sessions

Find sessions matching specific criteria:

Available filter options:

• --since DATE - Sessions modified since date (e.g., “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 (e.g., “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 (default), paths, json

3. Extract Data

Pull specific information from sessions:

Available extraction types:

• metadata - Session info (ID, timestamps, branch, working dir)
• user-prompts - All user messages
• tool-usage - Tool call statistics (which tools, how many times)
• 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 of key data

File Organization

Session logs themselves are stored by Claude Code in:

How Session Paths Work

Claude Code calculates the log directory from your working directory:

1. Take the absolute working directory path
2. Replace all / with -
3. Store logs in ~/.claude/projects/{transformed-path}/

Example:

All scripts in this skill handle this transformation automatically.

Use Cases

For Users

“What sessions are available?”

“Show me recent sessions with errors”

“How much data is in my last session?”

For Skills Integration

Retrospective Skill uses this skill to:

• List available sessions for user selection
• Check session sizes before processing
• Extract errors, tool usage, and statistics
• Filter sessions by timeframe or branch

Future Skills could use it to:

• Compare sessions across time
• Generate usage reports
• Debug specific session issues
• Archive or export session data

Requirements

Dependencies

• bash (v4.0+)
• jq (JSON parser) - Install with brew install jq

If jq is not installed, scripts will display installation instructions.

Session Logs

This skill requires Claude Code’s native session logs. These are automatically created by Claude Code when you use it. No manual setup needed.

Privacy & Security

What Data is Accessed

• Session log files in ~/.claude/projects/
• Contains all messages, tool calls, and responses from sessions
• Stored locally on your machine

Data Storage

• No data is sent to external services
• All processing happens locally
• Scripts only read logs, never modify them
• Extracted data stays in your terminal session unless you save it

Sensitive Information

If your sessions contained sensitive data:

• Session logs are stored locally only
• You control access to ~/.claude/projects/ directory
• Be cautious when sharing extracted data
• Consider project-specific access controls

Error Handling

All scripts exit with non-zero status on errors and output messages to stderr. You can check exit status in bash:

Common errors:

Troubleshooting

“Logs directory not found”

Cause: No sessions exist for the current project yet, or you’re in a different directory.

Solution:

• Check you’re in the correct project directory
• Verify Claude Code has been used in this project
• Manually check: ls ~/.claude/projects/

“Session file not found”

Cause: Session ID doesn’t exist or is incorrect.

Solution:

• List available sessions: scripts/list-sessions.sh
• Copy exact session ID from the list
• Ensure you’re in the correct project directory

“jq is required but not installed”

Cause: The jq JSON parser is not installed.

Solution:

“No sessions match the specified criteria”

Cause: Filter criteria are too restrictive.

Solution:

• Broaden criteria (e.g., longer timeframe)
• List all sessions first: scripts/list-sessions.sh
• Check filter syntax in help: scripts/filter-sessions.sh --help

Examples

Example 1: Finding Recent Work

Goal: See what you’ve worked on in the last 3 days

Output:

Example 2: Investigating Errors

Goal: Find all sessions with errors and see what failed

Example 3: Comparing Tool Usage

Goal: See which tools you use most often

Integration with Other Skills

This skill is designed as a utility skill for other skills to use:

Retrospecting Skill

Uses extracting-session-data to:

1. List available sessions for user selection
2. Check session complexity (size, line count)
3. Extract errors, tool calls, and statistics
4. Avoid loading large logs into context unnecessarily

Future Session Analysis Skills

Could use extracting-session-data to:

• Compare productivity across sessions
• Track tool usage trends over time
• Identify recurring error patterns
• Generate session summaries

Tips for Best Results

Efficient Filtering

Be specific with filters to reduce processing:

Check Size First

Before extracting from multiple sessions, check sizes:

This helps you understand how much data you’re working with.

Use Appropriate Extraction Types

Don’t extract everything if you only need specific data:

Future Enhancements

Planned improvements:

• Parallel processing for multi-session extraction
• Compressed session log support
• Export to standardized formats (CSV, JSON)
• Session comparison utilities
• Trend analysis across sessions

Feedback

Found an issue or have a suggestion?

• Modify scripts in scripts/ directory
• Update SKILL.md for Claude’s instructions
• Update this README.md for user documentation

Nearby

• PreviousScript Locate Logs