An interactive web-based viewer for Claude Code JSONL transcript files with real-time monitoring, usage tracking, and git integration.

Claude Code needs an observation tool. Observing is a different activity than coding - it's about reflection, understanding, and decision-making.

This tool enables:

• 🔍 Reflection on Changes - Review what Claude actually did, not just what you asked for
• 🗺️ Retrace Agent Actions - See the conversation branches, timeline of decisions, and evolution of solutions
• 📋 Easy Access to Context - Find past plans, todos, and commits without digging through files
• 🎯 Session Discovery - Quickly locate the correct session when resuming work
• ⏮️ Rollback Capability - Undo agent and standard changes through git integration (when enabled)

Claude Code is powerful, but without visibility into its actions, you're flying blind. This tool gives you the observation layer that makes Claude Code truly manageable for serious development work.

• Live file watching with automatic updates
• Session-based organization with color-coded cards
• Message count and token usage per session
• Last active timestamp tracking
• Configurable auto-refresh (1s to 60s intervals)

• Full-text search across all message content
• Clickable search results - click any result to load full file history
• --all flag - search all JSONL files on disk (e.g., myterm --all)
• file: prefix - filter by specific file (e.g., file:/path/to/file.jsonl)
• Highlighted matches - matching rows highlighted when viewing file
• Filter by message type (user, assistant, tool_result, file-history)
• Limit display (50, 100, 200, 500 entries)
• Session-specific filtering
• Interactive field selection

• Real-time Claude API usage monitoring
• 5-hour and 7-day usage windows
• Token consumption tracking with deltas
• Usage snapshot history
• Automatic API polling (10-second intervals)
• Backend-driven calculation pipeline

• Syntax highlighting for code blocks
• Markdown rendering for formatted text
• Screenshot display support
• Tool result visualization
• Collapsible message sections
• Dark theme optimized for readability

• View todo lists from Claude sessions
• Track ExitPlanMode entries
• Todo file integration
• Session-specific todo filtering

• Manual checkpoint creation
• Git repository discovery
• Per-project and per-repo git controls
• Checkpoint listing and management
• Git commit tracking
• Repository status monitoring

• Conversation flow visualization
• Message relationship tracking
• Fork detection (in development)
• Interactive timeline view

• Persistent settings storage
• Git enable/disable per project
• Git enable/disable per repository
• Customizable refresh intervals
• View mode preferences

pip install claude-log-viewer

git clone https://github.com/InDate/claude-log-viewer.git
cd claude-log-viewer
pip install -e .

claude-log-viewer

# Specify project to monitor
claude-log-viewer --project my-project

# Set maximum entries to display
claude-log-viewer --max-entries 1000

# Set file age filter (days)
claude-log-viewer --file-age 7

# Set port
claude-log-viewer --port 5001

Open your browser to:

http://localhost:5001

For searching log files from the command line:

# Search for a pattern across all projects
claude-log-tools search "error" --days 7

# Search within a specific project
claude-log-tools search "TODO" --project my-project

# Count entries per session/project
claude-log-tools count --days 3

# List sessions with metadata
claude-log-tools sessions --project my-project --days 14

The viewer will automatically load JSONL files from:

• ~/.claude/projects/ - Claude Code session transcripts
• ~/.claude/todos/ - Todo lists

• Search: Filter entries by any text content
  • Results are clickable - click to load the full file history
  • Add --all to search all files on disk (slower but comprehensive)
  • Use file:/path/to/file.jsonl to view a specific file
  • Matching rows are highlighted with a blue border
• Type Filter: Filter by entry type (user, assistant, tool_result, etc.)
• Limit: Control how many entries to display (50-500)
• Refresh: Manually reload all entries
• Auto-refresh: Enable automatic updates (1s-60s intervals)
• Timeline: Toggle between table and timeline visualization
• Settings: Configure git integration and preferences

• Click session card to filter entries for that session
• View message count, token usage, and last active time
• Access todos and plans for each session
• Color-coded for easy identification

• Click message content to open in modal
• Syntax highlighting for code
• Markdown rendering for formatted text
• Screenshot display support
• Copy content to clipboard

• Framework: Flask (Python 3.9+)
• File Watching: Watchdog for real-time monitoring
• Database: SQLite with WAL mode for concurrency
• API Polling: Background thread for usage updates
• Token Counting: tiktoken for accurate token calculation

• Vanilla JavaScript (ES6 modules)
• Markdown: markdown-it for rendering
• Syntax Highlighting: highlight.js
• No framework dependencies - lightweight and fast

• Async file processing: Queue-based worker thread
• Backend-driven calculations: Snapshot pipeline
• Bucket assignment algorithm: Efficient usage tracking
• Git integration: GitRollbackManager for checkpoints

• Database: ~/.claude/logviewer.db (SQLite)
• JSONL Files: ~/.claude/projects/*/agent-*.jsonl
• Screenshots: ~/.claude/projects/*/.claude/screenshots/
• Todos: ~/.claude/todos/

The application stores usage snapshots, session metadata, and git checkpoints in ~/.claude/logviewer.db.

If you need to rebuild the database (⚠️ this will delete all usage snapshot history):

# Stop the application first
# Then remove the database file
rm ~/.claude/logviewer.db

# Restart the application - it will create a fresh database
claude-log-viewer

The database will be recreated with:

• ✅ Empty usage_snapshots table (history lost)
• ✅ Fresh sessions table
• ✅ Empty git checkpoints
• ✅ All settings reset to defaults

Note: JSONL transcript files are NOT affected - only the viewer's internal database is deleted.

To preserve your usage history:

# Create backup
cp ~/.claude/logviewer.db ~/.claude/logviewer.db.backup

# Restore from backup
cp ~/.claude/logviewer.db.backup ~/.claude/logviewer.db

The database includes:

• usage_snapshots - API usage tracking over time
• sessions - Session metadata and statistics
• git_checkpoints - Manual and automatic checkpoints
• git_commits - Git commit tracking
• conversation_forks - Fork detection data
• settings - Application settings
• project_git_settings - Per-project git configuration
• repo_git_settings - Per-repository git configuration
• discovered_repos - Git repository discovery cache

See docs/rollback-proposal/ for detailed design documentation of upcoming features:

• Full Checkpoint Selector UI - Navigate through conversation checkpoints with context
• Fork Detection & Navigation - Automatic detection and visualization of conversation branches
• Session Branching - Visual representation of conversation forks
• Enhanced Session Management - Delete, rename, and resume sessions from UI
• Markdown Tool Results - Rich rendering of tool outputs
• Image Display - Inline image viewing in sessions

• Cross-Platform Testing - Only tested on macOS, needs Windows/Linux verification (Issue #5)

• ✅ Token Delta Calculation - Fixed in v1.0.1 (Issue #9)

Contributions are welcome! Please feel free to submit a Pull Request.

# Clone repository
git clone https://github.com/InDate/claude-log-viewer.git
cd claude-log-viewer

# Install in development mode
pip install -e .

# Run tests
pytest

# Run with development settings
python -m claude_log_viewer.app --max-entries 1000

• Cross-platform testing (Windows, Linux)
• Git rollback feature implementation (Milestones #1-6)
• UI/UX improvements
• Performance optimization
• Documentation improvements

MIT License - see LICENSE file for details.

• Repository: https://github.com/InDate/claude-log-viewer
• Issues: https://github.com/InDate/claude-log-viewer/issues
• PyPI: https://pypi.org/project/claude-log-viewer/
• Release: https://github.com/InDate/claude-log-viewer/releases/tag/v1.0.0

• Installation Guide
• Usage Tracking Architecture
• Rollback Proposal (planned feature)

Note: This tool is for viewing Claude Code session transcripts. It requires Claude Code to be installed and have created session files in ~/.claude/projects/.