Claude Code Log

A Python CLI tool that converts Claude Code transcript JSONL files into readable HTML and Markdown (plus JSON for tooling).

Quick demo:

Supercut

▶️ Feature walkthrough: six short chapters on the archive index and search, reading a session, folding and filtering, agents and forks, and live sessions.

TUI demo:

TUI

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.

[!NOTE] Experimental provider support is now available for single-session exports from Antigravity CLI (agy, alpha) and Codex CLI (codex, beta). Use --provider agy|codex --session-id <id>; these integrations may change as the upstream transcript formats evolve.

📄 View Example HTML Output - A real example generated from a sample of this project's development, regenerated on every docs build

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
• Watch Mode: claude-code-log watch re-converts as a session is written, so Markdown in an editor or Obsidian stays current; claude-code-log serve --watch makes an open session page grow as messages arrive, keeping your scroll position and folded sections
• 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
• Themes: --theme minimal gives a compact light/dark page where sub-agents and rewind forks are branches you can fold away, interleave with the main conversation or open side by side in columns (see Choosing a Theme)
• 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 wenmode
• Archive Search: claude-code-log serve serves the archive over loopback with full-text search across every project and session (see the archive search guide); every generated page also has in-page search
• Depth Levels & Compact Mode: --depth session|user|assistant|agent|tool|hook sets how deep into the message hierarchy to render and --compact merges repeated section headings — pairs well with --format md to feed past conversations back to an LLM for analysis or experience building
• 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 many tokens are my Claude Code sessions using?"
• "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?"
• "How can I feed a past session back to an LLM for analysis or experience building?"

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: Generate and open session HTML in browser
  • m: Generate and open session Markdown in browser
  • v: View session Markdown in embedded viewer (with table of contents)
  • c: Resume session in Claude Code with claude -r <sessionId>
  • a / d: Archive or delete the selected session
  • r: Restore an archived session back to a JSONL file
  • e: Toggle the expanded view of the selected row
  • p: Switch to project selector view
  • ?: Show all keybindings
  • H/M/V: Force regenerate HTML/Markdown (hidden shortcuts for development)
• 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 open the session's HTML, q to quit
• Row Expansion: Press e to expand the 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
• ~/.claude/projects/project-name/session-{session-id}.md - Markdown versions (with --format md, or on demand from the TUI)

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"

Feeding Past Conversations to an LLM

The combination --depth agent --format md --compact produces condensed Markdown suitable as context for an LLM to review or distill patterns from past work:

# Session → compact Markdown for LLM review
claude-code-log transcript.jsonl --depth agent --format md --compact -o session.md

# Whole project history
claude-code-log /path/to/project --depth agent --format md --compact

--depth levels (smallest → largest output):

• session — session structure only (headers and navigation)
• user — just user prompts and steering (useful as input to a downstream agent, e.g. building a requirements doc)
• assistant — user + assistant text only
• agent — adds sub-agents and key tool signals (WebSearch, WebFetch, agent delegations)
• tool — adds tools, cleaned of system/hook noise (default)
• hook — everything, including hooks and system notices

--detail full|high|low|minimal|user-only still works but is deprecated (removed in 2.0); it maps to hook, tool, agent, assistant and user respectively. Add --no-recaps to drop the ※ recap summaries, which otherwise appear at every depth.

--compact merges consecutive same-type sections in Markdown so runs of assistant responses share one heading instead of repeating ### 🤖 Assistant: for each.

Linking Commit SHAs

Plain 7c2e6f6-shaped tokens in transcript prose get turned into clickable commit links when the SHA is reachable from a local remote-tracking branch. github.com, gitlab.com, and bitbucket.org work out of the box. For self-hosted forges (in-house GitLab, Gitea, Forgejo, …), supply a URL template via --git-link:

# Self-hosted GitLab
claude-code-log /path/to/transcript --git-link 'https://{host}/{path}/-/commit/{sha}'

# Same thing via env var (useful for TUI / repeated invocations)
export CLAUDE_CODE_LOG_GIT_LINK='https://{host}/{path}/-/commit/{sha}'
claude-code-log --tui

Placeholders: {host}, {path}, {sha}. The template fires only when the static map doesn't already know the host, so a mix of GitHub repos + self-hosted GitLab gets correct links from both. SHAs not reachable from any local remote-tracking ref render as plain text — local-only work-in-progress commits never produce broken links.

Choosing a Theme

HTML output comes in themes, selected with --theme (on the default command, serve and watch, and for the TUI's HTML exports) or the CLAUDE_CODE_LOG_THEME environment variable:

• classic — the original look (the default)
• minimal — a compact light/dark theme: dense rows on a time rail, long content folded to short previews, and sub-agents and rewind forks drawn as branches you can fold away, interleave with the main conversation or open side by side in columns
• default — the built-in default, currently classic

claude-code-log --theme minimal

# Same thing via env var; an explicit --theme always wins over it
export CLAUDE_CODE_LOG_THEME=minimal
claude-code-log --theme classic   # still classic

Themes write the same files (combined_transcripts.html, session-*.html, …) rather than separate ones, and each page records the theme it was rendered in, so switching theme regenerates the whole archive (and switching back regenerates it again). --theme is HTML-only; with --format md it is ignored with a warning. An unknown CLAUDE_CODE_LOG_THEME value is an error. The themes guide walks through the minimal theme's toolbar, branch modes and dark mode, with screenshots.

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-id}.md          # Markdown version (--format md or TUI)
│   └── 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 token consumption tracking
• Syntax Highlighting: Code blocks properly formatted with markdown rendering
• Markdown Support: Server-side rendering with wenmode 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

Markdown Output Features

Markdown export provides a lightweight, portable alternative to HTML:

• GitHub-Flavored Markdown: Compatible with GitHub, GitLab, and other Markdown renderers
• Hierarchical Structure: Sessions organized with headers and collapsible details
• Message Excerpts: Section titles include message previews for quick navigation
• Code Preservation: Syntax highlighting hints via fenced code blocks
• Embedded Viewer: TUI includes built-in Markdown viewer with table of contents
• Image Support: Configurable image handling (placeholder, embedded base64, or referenced files)
• --compact Mode: Merge consecutive same-type section headings — most useful with --depth agent or assistant where tool stripping creates runs of Assistant or User sections

Installation

The recommended way is installing as a uv tool:

uv tool install claude-code-log

This will create a claude-code-log binary that you can call directly.

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

uvx claude-code-log@latest

Alternatively, if you prefer, install using pip:

pip install claude-code-log

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
# or if you want `claude-code-log` binary that works everywhere:
uv tool install --editable .

Contributing

See CONTRIBUTING.md for development setup, testing, and architecture documentation.

Community Extensions

Projects built on top of claude-code-log:

• archive-session by @lifeinchords. Wraps the CLI as three integration surfaces:
  • a Claude Code Skill
  • a Claude Code slash Command /archive-session for explicit in-chat invocation
  • a Claude Code PreCompact Hook that auto-archives transcripts and subagent logs right before context compaction

Cross-platform (macOS and Windows/MSYS).

TODO

• tutorial overlay
• integrate claude-trace request logs if present?
• 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 conversion libraries? Or WASM?)
• add special formatting for built-in tools: LS, NotebookRead, NotebookEdit, TodoRead
• 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 Claude Github Action and process output
• feed the filtered user messages to headless claude CLI to distill the user intent from the session
• animate gradient background in the classic theme
• merge git worktree directories