session-analyzer

Session Analyzer

Parse, extract, and analyze Claude Code session JSONL files. Zero dependencies — Python 3.10+ only.

When to Use

• User asks to analyze a Claude Code session (token usage, tool stats, duration)
• User wants a readable conversation transcript from a session
• User asks to find or list their sessions
• User wants to review what happened in a prior session
• User asks about cache hit rates, model usage, or session efficiency
• User asks "find the session where we discussed X"

Session File Locations

Claude Code stores sessions as JSONL files:

• Project sessions: ~/.claude/projects/{project-hash}/{session-id}.jsonl
• Project hash format: absolute repo path with / replaced by - (e.g., /Users/foo/repo → -Users-foo-repo)

Script Location

The CLI script is at scripts/session-analyzer.py relative to this SKILL.md file.

The plugin cache at ~/.claude/plugins/cache/ keeps multiple versions side-by-side. The canonical active version is recorded in ~/.claude/plugins/installed_plugins.json under the installPath field. Use it to resolve the correct script:

# Resolve via installed_plugins.json (canonical — always points to the active version)
SA=$(python3 -c "
import json, pathlib
data = json.loads((pathlib.Path.home() / '.claude/plugins/installed_plugins.json').read_text())
entry = data.get('plugins', {}).get('session-analyzer@lafollettlabs-claude-plugins', [{}])[0]
print(pathlib.Path(entry['installPath']) / 'skills/session-analyzer/scripts/session-analyzer.py')
" 2>/dev/null)

# Fallback for manual install (no version ambiguity)
[ -z "$SA" ] && SA=$(find ~/.claude/skills -path "*/session-analyzer/scripts/session-analyzer.py" -print -quit 2>/dev/null)

Argument Hints — User Intent to Flags

When the user asks something fuzzy, map their intent to the right command and flags:

User says	Command
"analyze my last session"	list --latest -p <cwd> → pipe path to analyze
"show yesterday's sessions"	list --since yesterday -p <cwd>
"the big session" / "longest session"	list --min-size 5M -p <cwd>
"sessions this week"	list --since 7d -p <cwd>
"find where we discussed CREW"	search "CREW" -p <cwd>
"what did we talk about on Monday?"	list --since 2026-04-21 --before 2026-04-22 -p <cwd>
"extract the full conversation"	extract <path> (saves to temp, prints clickable path)
"export to my docs folder"	extract <path> -o ~/Documents/
"show me the beginning"	extract <path> --head 10 (stdout preview)
"what was the last thing?"	extract <path> --tail 5 (stdout preview)
"show me with tool calls"	extract <path> --tools --timestamps
"how many tokens did we use?"	analyze <path>
"give me the JSON"	list --json / analyze --format json