Transcript Intelligence

Transcript Intelligence

Search, analyze, and extract knowledge from Claude Code session transcripts - your deep memory for past conversations, decisions, and solutions.

Quick Reference

Using sesh for Easy Access

The sesh CLI provides human-friendly access to transcripts by session name:

# Get transcript path by session name
sesh transcript my-session
# Output: /Users/you/.claude/projects/.../abc123.jsonl

# View transcript directly
cat $(sesh transcript my-session)

# Search within a named session
rg "keyword" $(sesh transcript my-session)

# Pipe to jq for structured queries
cat $(sesh transcript my-session) | jq 'select(.type == "user")'

# Get session info (includes transcript path)
sesh info my-session

# List sessions for current project
sesh list --project .

# List recent sessions
sesh list --limit 10

Benefits Over Manual Path Navigation

Transcript Location

Transcripts are stored in project-specific directories:

~/.claude/projects/
├── <project-hash-1>/
│   ├── <session-id-1>.jsonl
│   ├── <session-id-2>.jsonl
│   └── ...
├── <project-hash-2>/
│   └── ...
└── ...

Finding Your Project's Transcripts

Using sesh (recommended):

# List sessions for current project
sesh list --project .

# Get transcript path by name
sesh transcript my-session

# View session details including transcript
sesh info my-session

Manual approach:

# List all Claude project directories
ls -la ~/.claude/projects/

# Find transcripts for current project (by recent modification)
ls -lt ~/.claude/projects/*/  | head -20

# Find all transcripts modified in last 7 days
find ~/.claude/projects -name "*.jsonl" -mtime -7

Transcript Line Structure

Each line is a JSON object:

interface TranscriptLine {
  type: 'user' | 'assistant' | 'file-history-snapshot' | 'system' | 'summary';
  uuid: string;
  parentUuid: string | null;
  sessionId: string;
  timestamp: string;           // ISO 8601 format
  cwd: string;                 // Working directory
  version: string;             // Claude Code version
  gitBranch?: string;          // Git branch (if in repo)
  message: {
    role: 'user' | 'assistant';
    content: ContentBlock[] | string;
    model?: string;            // e.g., "claude-sonnet-4-20250514"
    usage?: {
      input_tokens: number;
      output_tokens: number;
    };
  };
  toolUseResult?: any;         // Result from tool execution
}

Content Block Types

The message.content field can contain:

Common Search Patterns

Search for Decisions

# Find discussions about specific topics
rg -i "decided|decision|chose|choice" ~/.claude/projects/<hash>/*.jsonl

# Find architectural decisions
rg -i "architecture|design|pattern" ~/.claude/projects/<hash>/*.jsonl

# Find trade-off discussions
rg -i "tradeoff|trade-off|pros and cons|alternative" ~/.claude/projects/<hash>/*.jsonl

Search for Solutions

# Find error resolutions
rg -i "fixed|resolved|solution|workaround" ~/.claude/projects/<hash>/*.jsonl

# Find specific error discussions
rg "error|exception|failed" ~/.claude/projects/<hash>/*.jsonl | rg -i "<error-text>"

# Find implementation discussions
rg -i "implemented|implementation|approach" ~/.claude/projects/<hash>/*.jsonl

Search by Time

# Find recent transcripts (last 24 hours)
find ~/.claude/projects -name "*.jsonl" -mtime -1

# Search within date range (using jq)
cat transcript.jsonl | jq -r 'select(.timestamp >= "2025-01-01" and .timestamp < "2025-01-07")'

Search User Messages Only

# Extract only user prompts
cat transcript.jsonl | jq -r 'select(.type == "user") | .message.content'

# Search user messages for keyword
cat transcript.jsonl | jq -r 'select(.type == "user") | .message.content' | rg -i "keyword"

Search Assistant Responses Only

# Extract assistant text responses
cat transcript.jsonl | jq -r 'select(.type == "assistant") | .message.content[] | select(.type == "text") | .text'

# Search assistant responses
cat transcript.jsonl | jq -r 'select(.type == "assistant") | .message.content[] | select(.type == "text") | .text' | rg -i "keyword"

Use Cases

1. Context Restoration After Compact

When context is compacted or cleared, search transcripts to restore important information:

# Using sesh (recommended) - search by session name
rg -C 3 "important|critical|remember|note" $(sesh transcript my-session)

# Find file modifications in named session
cat $(sesh transcript my-session) | jq '.message.content[] | select(.type == "tool_use" and (.name == "Write" or .name == "Edit"))'

# Manual approach with raw path
rg -C 3 "important|critical|remember|note" <transcript>.jsonl

2. Finding Past Solutions

Recall how you solved similar problems:

# Search for specific error across all sessions
rg -l "TypeError" ~/.claude/projects/<hash>/*.jsonl

# Get context around the solution
rg -C 5 "TypeError" <transcript>.jsonl

3. Session Analytics

Understand usage patterns:

# Count messages per session
wc -l ~/.claude/projects/<hash>/*.jsonl

# Token usage in session
cat transcript.jsonl | jq -r 'select(.message.usage) | .message.usage | "\(.input_tokens) in, \(.output_tokens) out"'

# Total tokens
cat transcript.jsonl | jq -s '[.[].message.usage | select(.) | .input_tokens + .output_tokens] | add'

4. Finding Specific Tool Uses

# Find all file writes
cat transcript.jsonl | jq 'select(.type == "assistant") | .message.content[] | select(.type == "tool_use" and .name == "Write")'

# Find all bash commands run
cat transcript.jsonl | jq 'select(.type == "assistant") | .message.content[] | select(.type == "tool_use" and .name == "Bash") | .input.command'

# Find files that were read
cat transcript.jsonl | jq 'select(.type == "assistant") | .message.content[] | select(.type == "tool_use" and .name == "Read") | .input.file_path'

5. Reconstructing Conversation Flow

# Get chronological conversation with timestamps
cat transcript.jsonl | jq -r '[.timestamp, .type, (if .type == "user" then .message.content else (.message.content[] | select(.type == "text") | .text[:100]) end)] | @tsv'

# Get user-assistant pairs
cat transcript.jsonl | jq -r 'select(.type == "user" or .type == "assistant") | "\(.type): \(if .message.content | type == "string" then .message.content else (.message.content[] | select(.type == "text") | .text[:200]) end)"'

Integration with /recall Command

This skill works alongside the /recall command for structured memory retrieval:

# /recall uses this skill to search transcripts
/recall "what did we decide about the API design?"

When invoked via /recall:

1. Identify relevant project hash
2. Search across all session transcripts
3. Extract relevant context with surrounding lines
4. Summarize findings

Workflow: Deep Memory Search

Prerequisites

• Know the topic or keyword to search
• Have sesh CLI available (or access to ~/.claude/projects/)
• Know approximate timeframe (optional)

Steps (Using sesh - Recommended)

1. List available sessions

   • List project sessions: sesh list --project .
   • Or list all recent: sesh list --limit 20

2. Search by session name

   • Search named session: rg -i "<keyword>" $(sesh transcript my-session)
   • Or get path first: sesh transcript my-session

3. Get context around matches

   • rg -C 5 "<keyword>" $(sesh transcript my-session)

4. Extract structured data

   • cat $(sesh transcript my-session) | jq 'select(.type == "user")'

5. Summarize findings

   • Compile key decisions/solutions
   • Note related discussions

Steps (Manual - Without sesh)

1. Identify project directory

   • List projects: ls ~/.claude/projects/
   • Find relevant project hash by examining recent files

2. Perform broad search

   • Search across all sessions: rg -i "<keyword>" ~/.claude/projects/<hash>/*.jsonl
   • Note which sessions have matches

3. Narrow to specific session

   • Focus on most relevant session
   • Get context: rg -C 5 "<keyword>" <session>.jsonl

4. Extract structured data

   • Use jq for specific fields
   • Parse tool uses if relevant

5. Summarize findings

   • Compile key decisions/solutions
   • Note related discussions

Validation

• Found relevant context
• Decisions/solutions extracted
• Context is sufficient to continue work

Performance Tips

Common jq Patterns

# Pretty print specific line types
cat transcript.jsonl | jq 'select(.type == "user")'

# Extract timestamps
cat transcript.jsonl | jq -r '.timestamp'

# Get unique models used
cat transcript.jsonl | jq -r '.message.model // empty' | sort -u

# Count by type
cat transcript.jsonl | jq -r '.type' | sort | uniq -c

# Get git branches used
cat transcript.jsonl | jq -r '.gitBranch // empty' | sort -u

Troubleshooting

Security Notes

• Transcripts may contain sensitive information
• Avoid searching for/exposing secrets, API keys, passwords
• Be cautious when sharing transcript excerpts
• Transcripts are local to your machine

Hook Event Integration

When the event-logger hook handler is enabled, hook events are logged to ~/.claude/hooks/ and can be indexed alongside transcripts for unified analysis.

Enabling Hook Event Logging

Add to your hooks.yaml:

builtins:
  event-logger:
    enabled: true

Unified Index

The transcript CLI indexes both transcripts and hook events:

# Build unified index
bun run bin/transcript.ts index build

# Check status (shows transcript + hook counts)
bun run bin/transcript.ts index status

# Run daemon to watch both
bun run bin/transcript.ts index daemon start

SQL JOINs

Query across transcripts and hook events:

-- Find blocked tool calls with transcript context
SELECT h.toolName, h.decision, l.content_text
FROM hook_events h
JOIN lines l ON h.session_id = l.session_id AND h.tool_use_id = l.uuid
WHERE h.decision = 'block';

See TYPES.md for complete hook event schema and JOIN patterns.

Reference Files