lanej/claude-tail

Claude Tail Skill

You are a Claude Code session log analysis specialist using the claude-tail tool. This skill provides comprehensive guidance for viewing, filtering, and analyzing Claude Code session logs.

Core Concepts

claude-tail reads Claude Code session logs (JSONL format) and displays them with:

• Syntax highlighting and colors
• Real-time following (like tail -f)
• Filtering by event type, tool, time range, or errors
• Multiple display modes (compact, verbose, stats, tools-only)

Basic Usage

View a Session Log

# View a specific log file (follows by default)
claude-tail ~/.claude/sessions/2024-01-15-session.jsonl

# View without following (read once and exit)
claude-tail --no-follow ~/.claude/sessions/2024-01-15-session.jsonl

# Read from stdin
cat session.jsonl | claude-tail

Follow Logs in Real-Time

# Follow mode is enabled by default
claude-tail session.jsonl

# Explicitly enable follow mode
claude-tail -f session.jsonl

# Follow multiple files
claude-tail session1.jsonl session2.jsonl

Watch for New Logs

# Watch all JSONL files in current directory
claude-tail --pattern "*.jsonl"

# Watch all session logs
claude-tail --pattern "~/.claude/sessions/*.jsonl"

Display Modes

Compact Mode

# Minimal output, one-line per event
claude-tail --compact session.jsonl

Verbose Mode

# Detailed output with full event information
claude-tail --verbose session.jsonl

Statistics Mode

# Show statistics about the session
claude-tail --stats session.jsonl

Tools-Only Mode

# Show only tool usage events
claude-tail --tools-only session.jsonl

Filtering

Filter by Event Type

# Show only specific event types (comma-separated)
claude-tail --type tool_use,error session.jsonl

# Common event types: tool_use, text, error, system
claude-tail --type text session.jsonl

Filter by Tool Name

# Show only specific tools (comma-separated)
claude-tail --tool Read,Write session.jsonl

# Show only bash commands
claude-tail --tool Bash session.jsonl

# Show only file operations
claude-tail --tool Read,Write,Edit session.jsonl

Filter by Time Range

# Show events after a specific time (HH:MM:SS)
claude-tail --after 14:30:00 session.jsonl

# Show events before a specific time
claude-tail --before 15:45:00 session.jsonl

# Show events in a time window
claude-tail --after 14:30:00 --before 15:45:00 session.jsonl

Show Only Errors

# Display only error events
claude-tail --errors-only session.jsonl

Display Options

Terminal Width and Wrapping

# Set custom terminal width
claude-tail --width 120 session.jsonl

# Disable line wrapping
claude-tail --no-wrap session.jsonl

# Combine options
claude-tail --width 80 --no-wrap session.jsonl

Common Workflows

Debug a Session

# Show all errors in a session
claude-tail --errors-only --no-follow session.jsonl

# Show tool usage with errors
claude-tail --tools-only --errors-only session.jsonl

# Verbose output for debugging
claude-tail --verbose --errors-only session.jsonl

Monitor Tool Usage

# Watch what tools are being called
claude-tail --tools-only -f session.jsonl

# Monitor specific tools in real-time
claude-tail --tool Bash,Read,Write -f session.jsonl

# Get tool usage statistics
claude-tail --stats --tools-only session.jsonl

Analyze Session Activity

# Review activity in a time window
claude-tail --after 10:00:00 --before 11:00:00 --no-follow session.jsonl

# See compact summary of a session
claude-tail --compact --no-follow session.jsonl

# Get detailed statistics
claude-tail --stats session.jsonl

Watch Live Sessions

# Follow the most recent session
claude-tail -f ~/.claude/sessions/$(ls -t ~/.claude/sessions/*.jsonl | head -1)

# Watch all new session files
claude-tail --pattern "~/.claude/sessions/*.jsonl"

# Monitor errors in real-time
claude-tail --errors-only -f current-session.jsonl

Advanced Usage

Combining Filters

# Show Read/Write operations with errors after 2pm
claude-tail --tool Read,Write \
           --errors-only \
           --after 14:00:00 \
           session.jsonl

# Monitor specific tools in compact mode
claude-tail --tool Bash,Grep,Read \
           --compact \
           -f session.jsonl

Session Log Analysis

# Quick session overview
claude-tail --stats --no-follow session.jsonl

# Detailed tool usage analysis
claude-tail --tools-only --verbose --no-follow session.jsonl

# Find all errors in a session
claude-tail --errors-only --verbose --no-follow session.jsonl

Debugging Workflows

# Debug a specific time period with full detail
claude-tail --verbose \
           --after 14:30:00 \
           --before 14:35:00 \
           --no-follow \
           session.jsonl

# Monitor for errors during development
claude-tail --errors-only --tools-only -f session.jsonl

# Watch file operations in real-time
claude-tail --tool Read,Write,Edit,Glob,Grep \
           --compact \
           -f session.jsonl

Session Log Location

Claude Code session logs are typically stored in:

~/.claude/sessions/*.jsonl

Find Recent Sessions

# List sessions by most recent
ls -lt ~/.claude/sessions/*.jsonl | head -5

# View the most recent session
claude-tail ~/.claude/sessions/$(ls -t ~/.claude/sessions/*.jsonl | head -1)

Common Event Types

• tool_use - Claude called a tool (Read, Write, Bash, etc.)
• text - Claude sent text output
• error - An error occurred
• system - System messages and events

Common Tools to Filter

• Read - File reading operations
• Write - File writing operations
• Edit - File editing operations
• Bash - Shell command execution
• Grep - Code search operations
• Glob - File pattern matching
• Task - Agent task launches
• WebFetch - Web content fetching
• WebSearch - Web search queries

Best Practices

1. Use follow mode for active sessions: Monitor live sessions with -f
2. Filter aggressively: Use --tool, --type, and time filters to focus on relevant events
3. Start with stats mode: Get an overview with --stats before diving into details
4. Use compact mode for overviews: Quickly scan many events with --compact
5. Use verbose mode for debugging: Get full detail when investigating issues
6. Watch for errors: Regular --errors-only checks help catch issues early
7. Analyze tool patterns: Use --tools-only to understand workflow patterns

Tips

• Follow mode is enabled by default (use --no-follow to disable)
• Combine multiple filters to narrow down events precisely
• Use time filters to focus on specific parts of a session
• Stats mode is great for session retrospectives
• Errors-only mode helps quickly identify problems
• Tools-only mode shows the "what" without the "why"

Quick Reference

# View and follow
claude-tail session.jsonl

# View once
claude-tail --no-follow session.jsonl

# Show stats
claude-tail --stats session.jsonl

# Only errors
claude-tail --errors-only session.jsonl

# Only tools
claude-tail --tools-only session.jsonl

# Filter by tool
claude-tail --tool Read,Write session.jsonl

# Filter by time
claude-tail --after 14:00:00 --before 15:00:00 session.jsonl

# Compact output
claude-tail --compact session.jsonl

# Verbose output
claude-tail --verbose session.jsonl

# Watch pattern
claude-tail --pattern "*.jsonl"