claude-session-jsonl

name	claude-session-jsonl
description	Parse, analyze, and extract information from Claude Code or Claudia session JSONL files. Supports two formats automatically — Claude Code (pretty-printed JSON with user/assistant/queue-operation records) and Claudia (strict JSONL with alternating request/response pairs). Use this skill whenever the user mentions a .jsonl session file, asks about token usage or costs from a Claude session, wants to review what happened in a conversation, asks to extract tool calls or thinking blocks, mentions "session file" or "session log", wants to summarize or search through a past interaction, or references a file path that looks like a session ID (UUID.jsonl) or thread timestamp (1234567890.123456.jsonl). Also trigger when the user pastes a Slack thread URL and wants to analyze, download, or review that conversation's session, when they want to compare sessions, debug a failed tool call from a log, or convert session data into another format.
argument-hint	<path-to-session.jsonl>

Claude Code Session JSONL

Analyze Claude Code / Agent SDK / Claudia session files using the bundled scripts. Always start with summary to understand the session before drilling into specifics.

The parser auto-detects the file format:

• Claude Code / Agent SDK: Pretty-printed JSON with user, assistant, queue-operation, last-prompt record types
• Claudia: Strict JSONL with alternating request/response pairs (used by the Claudia Slack bot — stored in S3 as sessions/{team}/{channel}/{thread_ts}.jsonl)

Choosing the Right Script

User wants to...	Script
Download a session from a Slack thread URL	download.js
Get a quick overview of a session	summary.js
Read the actual conversation	conversation.js
See what tools were called and their results	tools.js
Understand token costs or caching efficiency	tokens.js
Analyze cache breakpoints, masking, compaction	cache-analysis.js
Find something specific in the session	search.js
Get structured data for further processing	export-json.js

Scripts

All scripts are in ${CLAUDE_SKILL_DIR}/scripts/ and take a session JSONL file as the first argument. They share a common parser (parser.js) that handles the pretty-printed JSON format these files use.

Download — fetch session from S3

node ${CLAUDE_SKILL_DIR}/scripts/download.js <slack-thread-url> [--stage=prod] [--profile=name]
node ${CLAUDE_SKILL_DIR}/scripts/download.js --team=T123 --channel=C456 --thread=1234567890.123456

Downloads a Claudia session JSONL from S3 given a Slack thread URL or thread components. Saves to /tmp/session-{thread_ts}.jsonl by default (override with --output). Requires AWS CLI access to the Claudia S3 bucket.

Slack URL handling:

• Simple URL: https://x.slack.com/archives/C123/p1773001335899119 → extracts channel + thread_ts from the path
• Thread reply URL: https://x.slack.com/archives/C123/p177300...?thread_ts=1773655654.167289&cid=D0AK → uses thread_ts query param as the actual thread root (the p timestamp is just the reply); cid overrides channel if present
• If --team is not provided, it searches the bucket automatically

Bucket resolution (checked in order): SESSION_BUCKET env var → --bucket flag → env.yml → auto-discovery (lists S3 buckets via AWS CLI, finds one matching *claudia* for the stage)

When the user provides a Slack URL with --profile, just pass both directly — the script handles URL parsing, bucket discovery, and team search automatically:

node ${CLAUDE_SKILL_DIR}/scripts/download.js "<full-slack-url>" --profile=<name>

Summary — start here

node ${CLAUDE_SKILL_DIR}/scripts/summary.js <session.jsonl>

Outputs: session metadata (model, provider, version, duration, cwd), token usage with cache hit rate, tool call breakdown by name, and a preview of each user message.

Conversation — extract readable turns

node ${CLAUDE_SKILL_DIR}/scripts/conversation.js <session.jsonl> [--with-thinking] [--with-tools]

Outputs: user/assistant turns as markdown. Use --with-thinking to include Claude's internal reasoning and --with-tools to show tool call details inline.

Tools — list tool calls

node ${CLAUDE_SKILL_DIR}/scripts/tools.js <session.jsonl> [--tool=Name] [--errors-only] [--json]

Outputs: each tool call with input, result preview, and metadata. Use --tool=Bash to filter to a specific tool, --errors-only to find failures, or --json for machine-readable output.

Tokens — usage timeline

node ${CLAUDE_SKILL_DIR}/scripts/tokens.js <session.jsonl> [--json]

Outputs: per-API-call token breakdown (input, output, cache read, cache write) in a table, with totals, per-model breakdown, and cache hit percentage.

Cache Analysis — breakpoints, masking, compaction (Claudia only)

node ${CLAUDE_SKILL_DIR}/scripts/cache-analysis.js <session.jsonl>
node ${CLAUDE_SKILL_DIR}/scripts/cache-analysis.js <session.jsonl> --call=3
node ${CLAUDE_SKILL_DIR}/scripts/cache-analysis.js <session.jsonl> --json

Analyzes Claudia sessions for prompt caching correctness. For each API call, checks:

• BP1 (system prompt, 1h TTL): static block cached, dynamic block uncached
• BP2 (leapfrog bridge): old conversation BP kept from reconstruction to prevent 20-block lookback misses
• BP3 (masking boundary): breakpoint at last masked observation when batch masking fires
• BP4 (conversation): breakpoint on second-to-last message, correctly skipping thinking blocks
• Observation counts: total, masked, unmasked, by type
• Compaction config: trigger threshold, retain_turns
• Issues: BP limit violations, missing BPs, stale bridges, potential lookback gaps

Use --call=N to inspect a single API call. Use --json for machine-readable output.

Search — find content in session

node ${CLAUDE_SKILL_DIR}/scripts/search.js <session.jsonl> <pattern> [--type=user|assistant|tool|thinking]

Outputs: regex matches with surrounding context. Filter by content type to narrow results.

Export JSON — structured output for processing

node ${CLAUDE_SKILL_DIR}/scripts/export-json.js <session.jsonl> [--compact] [--no-thinking]

Outputs: clean JSON with metadata, token usage, tool summary, and ordered conversation. Use --compact to omit tool inputs, --no-thinking to strip thinking blocks.

Format Reference

Claude Code format: Four record types (queue-operation, user, assistant, last-prompt), with streaming chunks sharing a message.id and a parentUuid chain linking the conversation. For full details, see format.md.

Claudia format: Strict one-per-line JSONL with alternating pairs:

• {"type":"request","params":{model, max_tokens, system, messages, ...},"ts":"..."} — the exact payload sent to messages.create()
• {"type":"response","content":[...],"stopReason":"...","usage":{inputTokens, outputTokens, cacheReadTokens, cacheCreationTokens},"ts":"..."} — the response content and usage stats

The parser auto-detects the format and normalizes Claudia records internally so all scripts work with both formats.

Iterative Caching Testing Workflow

When the user wants to test Claudia's caching behavior by sending messages one at a time and analyzing after each, follow this workflow:

Setup

1. User provides a Slack thread URL and AWS profile
2. Download the session: node ${CLAUDE_SKILL_DIR}/scripts/download.js "<url>" --profile=<name>
3. Save the output path (e.g., /tmp/session-{thread_ts}.jsonl) for re-downloads

After each user message

Re-download the session (it grows with each message), then run these three scripts:

# 1. Re-download (overwrites the previous file)
node ${CLAUDE_SKILL_DIR}/scripts/download.js "<url>" --profile=<name> --output=/tmp/session-{thread_ts}.jsonl

# 2. Conversation — confirm what the user said
node ${CLAUDE_SKILL_DIR}/scripts/conversation.js /tmp/session-{thread_ts}.jsonl --with-tools

# 3. Cache analysis — breakpoints, masking, compaction, issues
node ${CLAUDE_SKILL_DIR}/scripts/cache-analysis.js /tmp/session-{thread_ts}.jsonl

What to report after each iteration

1. User message: Confirm what was said and how Claudia responded
2. Caching breakpoints: Are BP1-BP4 placed correctly per the design? (see docs/PROMPT-CACHING.md)
3. Cache performance: Hit rate trend — is it improving, stable, or degrading?
4. Observation masking: How many observations exist? Has batch masking fired? Should it have?
5. Compaction: Has it triggered? Is it correctly configured?
6. Issues: Any ⚠ issues from cache-analysis.js, plus manual observations
7. Gap tracking: Maintain a running table of gaps found across iterations