| 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
- User provides a Slack thread URL and AWS profile
- Download the session:
node ${CLAUDE_SKILL_DIR}/scripts/download.js "<url>" --profile=<name>
- 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:
node ${CLAUDE_SKILL_DIR}/scripts/download.js "<url>" --profile=<name> --output=/tmp/session-{thread_ts}.jsonl
node ${CLAUDE_SKILL_DIR}/scripts/conversation.js /tmp/session-{thread_ts}.jsonl --with-tools
node ${CLAUDE_SKILL_DIR}/scripts/cache-analysis.js /tmp/session-{thread_ts}.jsonl
What to report after each iteration
- User message: Confirm what was said and how Claudia responded
- Caching breakpoints: Are BP1-BP4 placed correctly per the design? (see
docs/PROMPT-CACHING.md)
- Cache performance: Hit rate trend — is it improving, stable, or degrading?
- Observation masking: How many observations exist? Has batch masking fired? Should it have?
- Compaction: Has it triggered? Is it correctly configured?
- Issues: Any
⚠ issues from cache-analysis.js, plus manual observations
- Gap tracking: Maintain a running table of gaps found across iterations
