# Session Analyzer

> Analyze and extract conversations from Claude Code session JSONL files. Use when the user asks to review, analyze, search, or extract transcripts from Claude Code sessions.

- **Type:** Skill
- **Install:** `agentstack add skill-clafollett-lafollettlabs-claude-plugins-session-analyzer`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [clafollett](https://agentstack.voostack.com/s/clafollett)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [clafollett](https://github.com/clafollett)
- **Source:** https://github.com/clafollett/lafollettlabs-claude-plugins/tree/main/plugins/session-analyzer/skills/session-analyzer

## Install

```sh
agentstack add skill-clafollett-lafollettlabs-claude-plugins-session-analyzer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

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

## Session Selection Workflow

When the user doesn't specify a session file directly:

1. Detect the current project from cwd (use `git rev-parse --show-toplevel`)
2. If user said "last" / "latest" / "most recent": run `list --latest -p ` to get the path directly
3. If user gave a date or description: use `list` filters or `search` to narrow candidates
4. If multiple matches: present a numbered list with dates and sizes, ask the user to pick
5. Once a session is selected: run `extract` or `analyze` on the full path

## Commands

### list — Find sessions

```bash
# All projects
python3 "$SA" list

# Sessions for a specific project
python3 "$SA" list --project /path/to/repo

# Filter by date (YYYY-MM-DD, today, yesterday, Nd, Nw, Nh)
python3 "$SA" list -p /path/to/repo --since yesterday
python3 "$SA" list -p /path/to/repo --since 7d --before today

# Filter by size
python3 "$SA" list -p /path/to/repo --min-size 1M

# Get just the most recent session's full path
python3 "$SA" list -p /path/to/repo --latest

# JSON output with full paths (for scripting / piping)
python3 "$SA" list -p /path/to/repo --json
```

**Date formats:** `YYYY-MM-DD`, `today`, `yesterday`, `3d` (3 days ago), `2w` (2 weeks ago), `6h` (6 hours ago)

**Size formats:** `500K`, `1M`, `5M`, `1G`

### search — Find sessions by content

```bash
# Search across all sessions for a project
python3 "$SA" search "CREW prototype" --project /path/to/repo

# Limit results
python3 "$SA" search "migration" -p /path/to/repo -n 5

# More context around matches
python3 "$SA" search "budget" -p /path/to/repo --context 150

# JSON output
python3 "$SA" search "Rembrandt" -p /path/to/repo --json
```

### extract — Conversation transcript

By default, `extract` saves to a temp file and prints the path (clickable in terminal).
The filename is auto-generated: `transcript-{date}-{session-name-or-id}.md`.
Use `--head`/`--tail` to preview turns directly in stdout.

```bash
# Full transcript → temp file (prints clickable path)
python3 "$SA" extract 

# Full transcript → specific directory (auto-names the file)
python3 "$SA" extract  -o /path/to/dir/

# Full transcript → specific filename
python3 "$SA" extract  -o /path/to/transcript.md

# Preview first 10 turns in stdout (safe for context window)
python3 "$SA" extract  --head 10

# Preview last 5 turns in stdout
python3 "$SA" extract  --tail 5

# With tool call summaries and timestamps
python3 "$SA" extract  --tools --timestamps

# With thinking blocks (collapsed in details tags)
python3 "$SA" extract  --thinking

# Include sidechain (agent/team) entries
python3 "$SA" extract  --sidechains
```

**Session naming:** If the user has set a custom session title (via Claude Code's rename feature), it appears in the filename. Otherwise falls back to a short session UUID.

**IMPORTANT for Claude:** When the user asks to "extract" or "export" a session, ALWAYS use file output (no `--head`/`--tail`). Print the resulting path so they can click it. Only use `--head`/`--tail` for quick peeks that the user wants to see inline.

### analyze — Session statistics

```bash
# Markdown report (duration, tokens, tools, files modified)
python3 "$SA" analyze 

# JSON output for piping or further processing
python3 "$SA" analyze  --format json
```

## Output Formats

- **list** → Markdown table (default), JSON with full paths (`--json`), or bare path (`--latest`)
- **search** → Markdown with snippets (default) or JSON (`--json`)
- **extract** → Date-stamped markdown file (temp dir or `-o` path); `--head`/`--tail` for stdout preview
- **analyze** → Markdown tables (default) or JSON (`--format json`)

## Important

- The script streams JSONL line-by-line — handles arbitrarily large session files
- Sidechain entries (sub-agent conversations) are excluded by default in `extract`
- The `analyze` command tracks files modified via Write/Edit tool calls
- Cache hit rate = `cache_read / (input + cache_read)` — higher is better
- `search` is case-insensitive substring matching across user and assistant text
- `list --latest` outputs a bare path — ideal for `$(...)` subshell piping

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [clafollett](https://github.com/clafollett)
- **Source:** [clafollett/lafollettlabs-claude-plugins](https://github.com/clafollett/lafollettlabs-claude-plugins)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** yes
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-clafollett-lafollettlabs-claude-plugins-session-analyzer
- Seller: https://agentstack.voostack.com/s/clafollett
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.