| name | session-transcripts |
| description | Search and analyze past Claude Code sessions to understand what happened, trace decisions, and investigate history. IMPORTANT: Always load this skill before searching session history or working with transcripts — it provides optimized jq scripts and shell tools that are far more efficient than raw grep. Use when searching session history, finding past sessions or conversations, tracing how something was created or built, investigating what happened in a previous session, reviewing sessions for issues or missteps, reading .jsonl transcript files, analyzing token usage, extracting conversation from transcripts, summarizing past sessions, or finding which sessions loaded or used a particular skill. |
Session Transcripts
Tools and schema reference for working with Claude Code session transcript JSONL files.
When to Use
- Searching session history to find past work or conversations
- Tracing how something was created, built, or decided in a past session
- Investigating what happened in a previous session
- Finding a past session by UUID or content search
- Reviewing a session for errors, missteps, or improvement opportunities
- Summarizing or extracting the conversation flow from a session
- Analyzing token usage or tool usage in a session
- Listing projects or sessions
- Finding which sessions loaded or used a particular skill
- Any task involving
~/.claude/projects/ JSONL files
Storage Layout
~/.claude/
├── projects/
│ └── <encoded-project-path>/ # e.g., -Users-bkudria-code-myproject
│ ├── <session-uuid>.jsonl # Full session transcripts
│ ├── agent-<agent-id>.jsonl # Sub-agent transcripts (old format)
│ ├── <session-uuid>/
│ │ └── subagents/
│ │ └── agent-<agent-id>.jsonl # Sub-agent transcripts (new format)
│ └── CLAUDE.md # Project instructions (not a transcript)
└── history.jsonl # Lightweight global history index
Path encoding: replace / and . with -. Example: /Users/me/.claude/skills/foo → -Users-me--claude-skills-foo
Available Scripts
All scripts are in ~/.claude/skills/session-transcripts/scripts/.
Discovery — find and list sessions
| Script | Purpose |
|---|
find-session.sh <uuid> | Find session file by UUID (partial match, truncated UUIDs OK) |
find-session.sh -s <term> | Search content across all sessions |
list-projects.sh | List all projects with session counts |
list-sessions.sh [path] | List sessions for a project |
find-subagent-files.sh <file> | Find all subagent transcript files for a session |
find-skill-usage.sh <name> [--project <path>] | Find sessions that loaded a specific skill |
External utilities (on PATH, not in scripts/)
| Command | Purpose | When to use |
|---|
shunt <cmd> [args] | Run any command and save stdout to a temp file, printing the path | Large outputs that need to be Read separately |
Extraction — structured views of a single session
| Script | Purpose | When to use |
|---|
extract-overview.jq | Quick stats (tokens, tools, duration) | First look at any session |
extract-tool-results.sh [--full] [--tools T] [--errors-only] | Tool calls paired with results via tool_use_id | Primary view for understanding what happened |
extract-conversation.jq | Conversation with brief tool descriptions | Understanding the conversational flow |
extract-activity.jq | One-line-per-turn timeline | Spotting patterns and timing gaps |
extract-errors.jq | Tool errors and stderr | Debugging failures |
extract-changes.jq | File operations log | Tracking what files were touched |
extract-agents.jq | Sub-agent spawns with prompts and model | Multi-agent sessions |
extract-compaction.jq | Compaction events with before/after stats | Long sessions hitting context limits |
extract-subagent-commands.jq | Sub-agent tool uses | What sub-agents did |
extract-skill-usage.jq | Skill invocations with timestamps | Which skills were loaded |
extract-thinking.jq | Thinking blocks with timestamps | Understanding Claude's reasoning |
extract-progress.jq | Non-agent progress entries (bash, hook, mcp) | Long-running commands and background activity |
Search — find specific content within a session
| Script | Purpose | When to use |
|---|
search-session.sh <file> <keyword> [--context N] | Keyword search across text, tool inputs, and results | Finding mentions of a topic |
search-tool-calls.sh <file> [--path P] [--tools T] [--commands-only] | Filter tool calls by path/tool name | Finding specific file operations |
Libraries
| File | Purpose |
|---|
lib.jq | Shared jq functions for all .jq scripts |
lib.sh | Shared bash functions for all .sh scripts |
Usage Examples
SCRIPTS=~/.claude/skills/session-transcripts/scripts
$SCRIPTS/find-session.sh 77d54f93
$SCRIPTS/extract-overview.jq /path/to/session.jsonl
$SCRIPTS/extract-tool-results.sh /path/to/session.jsonl
$SCRIPTS/search-session.sh /path/to/session.jsonl "authentication" --context 3
$SCRIPTS/search-tool-calls.sh /path/to/session.jsonl --tools "Write,Edit" --path "lib.jq"
$SCRIPTS/find-skill-usage.sh skillcraft
$SCRIPTS/list-sessions.sh /Users/bkudria/code/myproject
Reviewing a Session
If your task is to review or audit a past session, load workflows/review.md before running extraction scripts. It sequences the primary view (extract-tool-results.sh), error isolation (--errors-only), and keyword search (search-session.sh) so you don't default to broad extractions when a targeted one would isolate the signal in one call.
Tips
- Truncated UUIDs:
find-session.sh accepts truncated UUIDs (first segment only, e.g. b366b3b0). Prefix matching is tried first (fast), with substring fallback.
- Saving output to a file: Use
shunt <command> [args...] — it saves stdout to a temp file and prints the path. Never use shell > redirection to external paths (triggers permission prompts).
- Large transcripts (>256KB file size): Use
shunt to save extract-conversation.jq output, then Read the printed path. Check file size first (ls -l or extract-overview.jq) — most sessions are well under this threshold and can be processed directly.
- Quick stats: Use
extract-overview.jq before reading a transcript to understand its scope.
- Auditing skill usage: Start with
extract-skill-usage.jq (timestamps within one session) and find-skill-usage.sh (cross-session) — these produce ground-truth lists instead of inferring from conversation extractions.
- Ad-hoc queries: See
references/jq-recipes.md for common jq one-liners.
- Schema details: See
references/transcript-schema.md for full JSONL field documentation.
Dependencies
- jq — JSON processor (
brew install jq), required by all .jq scripts
Reference Files
| File | Contents |
|---|
references/transcript-schema.md | Full JSONL schema with all entry types and fields |
references/jq-recipes.md | Ad-hoc jq one-liners for custom queries |
workflows/review.md | Structured session review toolkit |
