Deprecated: Function get_magic_quotes_gpc() is deprecated in /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php on line 99

Deprecated: The each() function is deprecated. This message will be suppressed on further calls in /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php on line 619

Warning: Cannot modify header information - headers already sent by (output started at /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php:99) in /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php on line 1169

Warning: Cannot modify header information - headers already sent by (output started at /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php:99) in /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php on line 1176

Warning: Cannot modify header information - headers already sent by (output started at /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php:99) in /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php on line 1176

Warning: Cannot modify header information - headers already sent by (output started at /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php:99) in /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php on line 1176

Warning: Cannot modify header information - headers already sent by (output started at /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php:99) in /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php on line 1176

Warning: Cannot modify header information - headers already sent by (output started at /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php:99) in /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php on line 1176

Warning: Cannot modify header information - headers already sent by (output started at /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php:99) in /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php on line 1176

Warning: Cannot modify header information - headers already sent by (output started at /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php:99) in /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php on line 1176

Warning: Cannot modify header information - headers already sent by (output started at /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php:99) in /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php on line 1176

Warning: Cannot modify header information - headers already sent by (output started at /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php:99) in /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php on line 1176

Warning: Cannot modify header information - headers already sent by (output started at /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php:99) in /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php on line 1176

Warning: Cannot modify header information - headers already sent by (output started at /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php:99) in /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php on line 1176

Warning: Cannot modify header information - headers already sent by (output started at /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php:99) in /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php on line 1176

Warning: Cannot modify header information - headers already sent by (output started at /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php:99) in /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php on line 1176

Warning: Cannot modify header information - headers already sent by (output started at /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php:99) in /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php on line 1176

Warning: Cannot modify header information - headers already sent by (output started at /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php:99) in /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php on line 1176

Warning: Cannot modify header information - headers already sent by (output started at /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php:99) in /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php on line 1176

Warning: Cannot modify header information - headers already sent by (output started at /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php:99) in /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php on line 1176

Warning: Cannot modify header information - headers already sent by (output started at /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php:99) in /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php on line 1176

Warning: Cannot modify header information - headers already sent by (output started at /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php:99) in /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php on line 1176

Warning: Cannot modify header information - headers already sent by (output started at /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php:99) in /hermes/walnacweb04/walnacweb04ab/b2791/pow.jasaeld/htdocs/De1337/nothing/index.php on line 1176
8000 GitHub - daaain/claude-code-log: A Python CLI tool that converts Claude Code transcript JSONL files into readable HTML format.
Nothing Special   »   [go: up one dir, main page]

Skip to content

daaain/claude-code-log

Repository files navigation

Claude Code Log

A Python CLI tool that converts Claude Code transcript JSONL files into readable HTML format.

Browser log demo:

claude_code_log.webm

TUI demo:

Kapture.2025-07-24.at.22.54.51small.webm

Project Overview

📋 View Changelog - See what's new in each release

This tool generates clean, minimalist HTML pages showing user prompts and assistant responses chronologically. It's designed to create a readable log of your Claude Code interactions with support for both individual files and entire project hierarchies.

See example log (generated from real usage on this project).

Quickstart

TL;DR: run the command below and browse the pages generated from your entire Claude Code archives:

uvx claude-code-log@latest --open-browser

Key Features

  • Interactive TUI (Terminal User Interface): Browse and manage Claude Code sessions with real-time navigation, summaries, and quick actions for HTML export and session resuming
  • Project Hierarchy Processing: Process entire ~/.claude/projects/ directory with linked index page
  • Individual Session Files: Generate separate HTML files for each session with navigation links
  • Single File or Directory Processing: Convert individual JSONL files or specific directories
  • Session Navigation: Interactive table of contents with session summaries and quick navigation
  • Token Usage Tracking: Display token consumption for individual messages and session totals
  • Runtime Message Filtering: JavaScript-powered filtering to show/hide message types (user, assistant, system, tool use, etc.)
  • Chronological Ordering: All messages sorted by timestamp across sessions
  • Interactive timeline: Generate an interactive, zoomable timeline grouped by message times to navigate conversations visually
  • Cross-Session Summary Matching: Properly match async-generated summaries to their original sessions
  • Date Range Filtering: Filter messages by date range using natural language (e.g., "today", "yesterday", "last week")
  • Rich Message Types: Support for user/assistant messages, tool use/results, thinking content, images
  • System Command Visibility: Show system commands (like init) in expandable details with structured parsing
  • Markdown Rendering: Server-side markdown rendering with syntax highlighting using mistune
  • Floating Navigation: Always-available back-to-top button and filter controls
  • CLI Interface: Simple command-line tool using Click

What Problems Does This Solve?

This tool helps you answer questions like:

  • "How can I review all my Claude Code conversations?"
  • "What did I work on with Claude yesterday/last week?"
  • "How much are my Claude Code sessions costing?"
  • "How can I search through my entire Claude Code history?"
  • "What tools did Claude use in this project?"
  • "How can I share my Claude Code conversation with others?"
  • "What's the timeline of my project development?"
  • "How can I analyse patterns in my Claude Code usage?"

Usage

Interactive TUI (Terminal User Interface)

The TUI provides an interactive interface for browsing and managing Claude Code sessions with real-time navigation, session summaries, and quick actions.

# Launch TUI for all projects (default behavior)
claude-code-log --tui

# Launch TUI for specific project directory
claude-code-log /path/to/project --tui

# Launch TUI for specific Claude project
claude-code-log my-project --tui  # Automatically converts to ~/.claude/projects/-path-to-my-project

TUI Features:

  • Session Listing: Interactive table showing session IDs, summaries, timestamps, message counts, and token usage
  • Smart Summaries: Prioritizes Claude-generated summaries over first user messages for better session identification
  • Working Directory Matching: Automatically finds and opens projects matching your current working directory
  • Quick Actions:
    • h or "Export to HTML" button: Generate and open session HTML in browser
    • c or "Resume in Claude Code" button: Continue session with claude -r <sessionId>
    • r or "Refresh" button: Reload session data from files
    • p or "Projects View" button: Switch to project selector view
  • Project Statistics: Real-time display of total sessions, messages, tokens, and date range
  • Cache Integration: Leverages existing cache system for fast loading with automatic cache validation
  • Keyboard Navigation: Arrow keys to navigate, Enter to expand row details, q to quit
  • Row Expansion: Press Enter to expand selected row showing full summary, first user message, working directory, and detailed token usage

Default Behavior (Process All Projects)

# Process all projects in ~/.claude/projects/ (default behavior)
claude-code-log

# Explicitly process all projects
claude-code-log --all-projects

# Process all projects and open in browser
claude-code-log --open-browser

# Process all projects with date filtering  
claude-code-log --from-date "yesterday" --to-date "today"
claude-code-log --from-date "last week"

# Skip individual session files (only create combined transcripts)
claude-code-log --no-individual-sessions

This creates:

  • ~/.claude/projects/index.html - Top level index with project cards and statistics
  • ~/.claude/projects/project-name/combined_transcripts.html - Individual project pages (these can be several megabytes)
  • ~/.claude/projects/project-name/session-{session-id}.html - Individual session pages

Single File or Directory Processing

# Single file
claude-code-log transcript.jsonl

# Specific directory
claude-code-log /path/to/transcript/directory

# Custom output location
claude-code-log /path/to/directory -o combined_transcripts.html

# Open in browser after conversion
claude-code-log /path/to/directory --open-browser

# Filter by date range (supports natural language)
claude-code-log /path/to/directory --from-date "yesterday" --to-date "today"
claude-code-log /path/to/directory --from-date "3 days ago" --to-date "yesterday"

File Structure

  • claude_code_log/parser.py - Data extraction and parsing from JSONL files
  • claude_code_log/renderer.py - HTML generation and template rendering
  • claude_code_log/converter.py - High-level conversion orchestration
  • claude_code_log/cli.py - Command-line interface with project discovery
  • claude_code_log/models.py - Pydantic models for transcript data structures
  • claude_code_log/templates/ - Jinja2 HTML templates
    • transcript.html - Main transcript viewer template
    • index.html - Project directory index template
  • pyproject.toml - Project configuration with dependencies

Development

The project uses:

  • Python 3.12+ with uv package management
  • Click for CLI interface and argument parsing
  • Pydantic for robust data modeling and validation
  • dateparser for natural language date parsing
  • Standard library for JSON/HTML processing
  • Minimal dependencies for portability
  • mistune for quick Markdown rendering

Development Commands

Testing

The project uses a categorized test system to avoid async event loop conflicts between different testing frameworks:

Test Categories

  • Unit Tests (no mark): Fast, standalone tests with no external dependencies
  • TUI Tests (@pytest.mark.tui): Tests for the Textual-based Terminal User Interface
  • Browser Tests (@pytest.mark.browser): Playwright-based tests that run in real browsers

Running Tests

# Run only unit tests (fast, recommended for development)
uv run pytest -m "not (tui or browser)"

# Run TUI tests (isolated event loop)
uv run pytest -m tui

# Run browser tests (requires Chromium)
uv run pytest -m browser

# Run all tests in sequence (separated to avoid conflicts)
uv run pytest -m "not tui and not browser"; uv run pytest -m tui; uv run pytest -m browser

Prerequisites

Browser tests require Chromium to be installed:

uv run playwright install chromium

Why Test Categories?

The test suite is categorized because:

  • TUI tests use Textual's async event loop (run_test())
  • Browser tests use Playwright's internal asyncio
  • pytest-asyncio manages async test execution

Running all tests together can cause "RuntimeError: This event loop is already running" conflicts. The categorization ensures reliable test execution by isolating different async frameworks.

Test Coverage

Generate test coverage reports:

# Run tests with coverage
uv run pytest --cov=claude_code_log --cov-report=html --cov-report=term

# Generate HTML coverage report only
uv run pytest --cov=claude_code_log --cov-report=html

# View coverage in terminal
uv run pytest --cov=claude_code_log --cov-report=term-missing

HTML coverage reports are generated in htmlcov/index.html.

Comprehensive Testing & Style Guide: The project includes extensive testing infrastructure and visual documentation. See test/README.md for details on:

  • Unit Tests: Template rendering, message type handling, edge cases
  • Test Coverage: 78%+ coverage across all modules with detailed reporting
  • Visual Style Guide: Interactive documentation showing all message types
  • Representative Test Data: Real-world JSONL samples for development
  • Style Guide Generation: Create visual documentation with uv run python scripts/generate_style_guide.py

Code Quality

  • Format code: ruff format
  • Lint and fix: ruff check --fix
  • Type checking: uv run pyright and uv run ty check

All Commands

  • Test (Unit only): uv run pytest
  • Test (TUI): uv run pytest -m tui
  • Test (Browser): uv run pytest -m browser
  • Test (All categories): uv run pytest -m "not tui and not browser"; uv run pytest -m tui; uv run pytest -m browser
  • Test with Coverage: uv run pytest --cov=claude_code_log --cov-report=html --cov-report=term
  • Format: ruff format
  • Lint: ruff check --fix
  • Type Check: uv run pyright and uv run ty check
  • Generate Style Guide: uv run python scripts/generate_style_guide.py

Test with Claude transcript JSONL files typically found in ~/.claude/projects/ directories.

Release Process (For Maintainers)

The project uses an automated release process with semantic versioning. Here's how to create and publish a new release:

Quick Release

# Bump version and create release (patch/minor/major)
just release-prep patch    # For bug fixes
just release-prep minor    # For new features
just release-prep major    # For breaking changes

# Or specify exact version
just release-prep 0.4.3

# Preview what would be released
just release-preview

# Push to PyPI and create GitHub release
just release-push
  1. GitHub Release Only: If you need to create/update just the GitHub release:

    just github-release          # For latest tag
    just github-release 0.4.2    # For specific version

Cache Structure and Benefits

The tool implements a sophisticated caching system for performance:

  • Cache Location: .cache/ directory within each project folder
  • Session Metadata: Pre-parsed session information (IDs, summaries, timestamps, token usage)
  • Timestamp Index: Enables fast date-range filtering without parsing full files
  • Invalidation: Automatic detection of stale cache based on file modification times
  • Performance: 10-100x faster loading for large projects with many sessions

The cache is transparent to users and automatically rebuilds when:

  • Source JSONL files are modified
  • New sessions are added
  • Cache structure version changes

Project Hierarchy Output

When processing all projects, the tool generates:

~/.claude/projects/
├── index.html                           # Master index with project cards
├── project1/
│   ├── combined_transcripts.html        # Combined project page
│   ├── session-{session-id}.html        # Individual session pages
│   └── session-{session-id2}.html       # More session pages...
├── project2/
│   ├── combined_transcripts.html
│   └── session-{session-id}.html
└── ...

Index Page Features

  • Project Cards: Each project shown as a clickable card with statistics
  • Session Navigation: Expandable session list with summaries and quick access to individual session files
  • Summary Statistics: Total projects, transcript files, and message counts with token usage
  • Recent Activity: Projects sorted by last modification date
  • Quick Navigation: One-click access to combined transcripts or individual sessions
  • Clean URLs: Readable project names converted from directory names

Message Types Supported

  • User Messages: Regular user inputs and prompts
  • Assistant Messages: Claude's responses with token usage display
  • Summary Messages: Session summaries with cross-session matching
  • System Commands: Commands like init shown in expandable details with structured parsing
  • Tool Use: Tool invocations with collapsible details and special TodoWrite rendering
  • Tool Results: Tool execution results with error handling
  • Thinking Content: Claude's internal reasoning processes
  • Images: Pasted images and screenshots

HTML Output Features

  • Responsive Design: Works on desktop and mobile
  • Runtime Message Filtering: JavaScript controls to show/hide message types with live counts
  • Session Navigation: Interactive table of contents with session summaries and timestamp ranges
  • Token Usage Display: Individual message and session-level to 86AD ken consumption tracking
  • Syntax Highlighting: Code blocks properly formatted with markdown rendering
  • Markdown Support: Server-side rendering with mistune including:
    • Headers, lists, emphasis, strikethrough
    • Code blocks and inline code
    • Links, images, and tables
    • GitHub Flavored Markdown features
  • Collapsible Content: Tool use, system commands, and long content in expandable sections
  • Floating Controls: Always-available filter button, details toggle, and back-to-top navigation
  • Cross-Session Features: Summaries properly matched across async sessions

Installation

Install using pip:

pip install claude-code-log

Or run directly with uvx (no separate installation step required):

uvx claude-code-log@latest

Or install from source:

git clone https://github.com/daaain/claude-code-log.git
cd claude-code-log
uv sync
uv run claude-code-log

TODO

  • tutorial overlay
  • integrate claude-trace request logs if present?
  • Localised number formatting and timezone adjustment runtime? For this we'd need to make Jinja template variables more granular
  • convert images to WebP as screenshots are often huge PNGs – this might be time consuming to keep redoing (so would also need some caching) and need heavy dependencies with compilation (unless there are fast pure Python conversation libraries? Or WASM?)
  • add special formatting for built-in tools: Bash, Glob, Grep, LS, exit_plan_mode, Read, Edit, MultiEdit, Write, NotebookRead, NotebookEdit, WebFetch, TodoRead, TodoWrite, WebSearch
    • render Edit / MultiEdit as diff(s)?
  • do we need to handle compacted conversation?
  • Thinking block should have Markdown rendering as sometimes they have formatting
  • system blocks like init also don't render perfectly, losing new lines
  • add ccusage like daily summary and maybe some textual summary too based on Claude generate session summaries? – import logs from @claude Github Actions
  • stream logs from @claude Github Actions, see octotail
  • wrap up CLI as Github Action to run after Cladue Github Action and process output
  • extend into a VS Code extension that reads the JSONL real-time and displays stats like current context usage and implements a UI to see messages, todos, permissions, config, MCP status, etc
  • feed the filtered user messages to headless claude CLI to distill the user intent from the session
  • filter message type on Python (CLI) side too, not just UI
  • Markdown renderer
  • figure out minimum Python version and introduce a testing matrix
  • add minimalist theme and make it light + dark; animate gradient background in fancy theme
  • do we need special handling for hooks?

About

A Python CLI tool that converts Claude Code transcript JSONL files into readable HTML format.

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Contributors 7

0