Claude Code Log Trajectory

English | 繁體中文

A Python CLI tool that converts Claude Code transcript JSONL files into readable HTML and Markdown formats — plus a trajectory timeline view (per-category swimlanes, zoomable, self-contained HTML) and an opencode provider.

[!NOTE] This is a fork of daaain/claude-code-log — all credit for the core tool goes to its authors. On top of everything the upstream tool does, this fork adds:

• --format trajectory — renders each session as a self-contained timeline page: per-category swimlanes with a multi-select filter, a filterable event ledger, a details panel, light/dark aware, with wheel-zoom, drag-select range filtering, and time/sequence projections.
• Multi-format output — -f html,trajectory,md,json (comma-separated); requesting html+trajectory renders them cross-linked with the index listing both.
• --provider opencode — reads opencode sessions (both the current SQLite storage and the legacy JSON storage), including sub-agent child sessions, tool calls, and token usage — all output formats work, trajectory included.

Browser log demo:

Browser log

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 Antigravity CLI (agy, alpha), Codex CLI (codex, beta), and opencode (opencode, beta, added by this fork). Use --provider agy|codex|opencode; these integrations may change as the upstream transcript formats evolve.

📄 View Example HTML Output - A real example (standard transcript + trajectory timeline) generated from a sample of the upstream project's development, regenerated on every docs build

🛠️ Example 2: Building This Fork - The actual (sanitized) Claude Code session in which this fork's trajectory format and opencode provider were developed, rendered by the tool itself — see the whole process as a zoomable trajectory timeline

Quickstart

TL;DR: one bare command renders everything — your Claude Code, Codex, and opencode archives, each session as a standard transcript + a trajectory timeline (cross-linked) + machine-readable JSON:

uvx claude-code-log-trajectory --open-browser

Default behavior (this fork)

Two defaults differ from the upstream tool:

1. --format is comma-separated and defaults to html,trajectory,json — e.g. -f html,trajectory,md. When html and trajectory are both requested they come out cross-linked ("⧖ View Trajectory Timeline" ↔ "transcript view"). Pass a single value (-f html, -f trajectory, -f md, -f json) to get just one. An explicit --output file suffix (.md, .json, …) still infers its format, and -o - (stdout) falls back to a single html document. (-f all was removed — list the formats you want.)

2. A bare invocation renders every provider — with no INPUT_PATH, no --provider, and no --projects-dir, the tool walks all archives it can find on the machine, in order:

   • Claude Code (~/.claude/projects/, honors $CLAUDE_CONFIG_DIR) — its index.html is what --open-browser opens
   • Codex (~/.codex/sessions/, honors $CODEX_HOME)
   • opencode (~/.local/share/opencode/, honors $XDG_DATA_HOME)

   Headless runs are covered too: claude -p, codex exec, and opencode run all persist sessions to these same locations by default (opt-outs like codex exec --ephemeral or Claude's CLAUDE_CODE_SKIP_PROMPT_HISTORY obviously leave nothing to render).

   Providers without local data are skipped with a Skipping <name>: no local data found. note, and one provider failing never aborts the others. --provider is comma-separated too — --provider claude,codex renders exactly those, in that order; with an INPUT_PATH or --session-id pass exactly one provider.

What you get

A real bare run (claude-code-log-trajectory -o ~/report) on a machine with all three providers prints:

Processing all projects in /Users/you/.claude/projects...
Successfully processed 350 projects and created index at ~/report/index.html
Processing codex sessions...
Processed 51 codex project(s) and created index at ~/report/codex/index.html
Processing opencode sessions...
Processed 55 opencode project(s) and created index at ~/report/opencode/index.html

and produces this layout (every page self-contained — copy anywhere, open offline):

~/report/
├── index.html                                  # Claude Code overview (all projects)
├── all-projects-summary.json                   # machine-readable overview
├── <project-dir>/                              # one dir per Claude project (cwd-encoded name)
│   ├── combined_transcripts.html               #   all sessions, transcript view
│   ├── combined_transcripts.trajectory.html    #   all sessions, trajectory view
│   ├── combined_transcripts.json               #   all sessions, structured JSON
│   ├── session-<id>.html                       #   per-session transcript
│   ├── session-<id>.trajectory.html            #   per-session trajectory
│   └── session-<id>.json                       #   per-session JSON
├── codex/
│   ├── index.html                              # Codex overview
│   └── <project-dir>/…                         #   same per-project structure
└── opencode/
    ├── index.html                              # opencode overview
    └── <project-dir>/…

Every index lists projects grouped by working directory, with per-session links to both flavours (session link + ⧖ trajectory link) and a Variants row on each project card. Without -o, Claude output lands in-place under ~/.claude/projects/ and each extra provider writes to <provider_home>/claude-code-log/ (the session archives themselves are never touched).

Narrow it down when you want just one thing:

uvx claude-code-log-trajectory -f html             # all providers, standard HTML only
uvx claude-code-log-trajectory --provider opencode # opencode only, both flavours
uvx claude-code-log-trajectory --provider codex -f trajectory

Key Features

• Fully offline output (this fork): every generated page is self-contained — no CDN scripts, no external stylesheets, no network fetches. Third-party libraries (vis-timeline for the interactive timeline) are vendored into the package and inlined at render time, so reports render on intranets and air-gapped machines
• Trajectory timeline view (this fork): --format trajectory renders each session as a self-contained swimlane timeline (per-category lanes + event ledger + details panel); -f html,trajectory produces both flavours cross-linked
• opencode provider (this fork): --provider opencode renders your opencode session archives (SQLite + legacy JSON storage) in any output format
• 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
• Detail Levels & Compact Mode: --detail full|high|low|minimal|user-only filters by verbosity 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 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?"
• "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>
  • r: Reload session data from files
  • p: Switch to project selector view
  • 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 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
• ~/.claude/projects/project-name/session-{session-id}.md - Markdown versions (generated on-demand via 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 --detail low --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 --detail low --format md --compact -o session.md

# Whole project history
claude-code-log /path/to/project --detail low --format md --compact

--detail levels (smallest → largest output):

• user-only — just user prompts and steering (useful as input to a downstream agent, e.g. building a requirements doc)
• minimal — user + assistant text only
• low — interaction-focused; keeps WebSearch, WebFetch, and Task (agent delegations) as key signals
• high — detailed but cleaned; drops system/hook noise
• full — everything (default)

--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.

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 (on-demand via 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 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

Trajectory View (this fork)

--format trajectory renders each session as a self-contained single-file timeline instead of the card-style transcript — useful when you want to see the shape of a session (how much time went to thinking vs tools, where the long stalls were, how sub-agents fanned out) rather than read it top to bottom:

# Trajectory pages for a whole project directory (index reused, links point at trajectory pages)
claude-code-log-trajectory ~/.claude/projects/-my-project --format trajectory

# Both flavours, cross-linked ("View Trajectory Timeline" ↔ "transcript view")
claude-code-log-trajectory -f html,trajectory --open-browser

What's on the page:

• One swimlane per category — user / async result / system / assistant / thinking / sub-assistant / tool use / tool result (errors in red) / memory — with turn markers (t1, t2, …). Categories mirror the standard transcript's classification, so the two views of a session always agree
• Multi-select category filter — toggle chips (with counts) show/hide categories; the swimlanes compact to the selected ones and the ledger filters along
• Event ledger — every event as a row with a category chip and a content preview; click a row or a span for the full content and timing details
• Interactions — wheel = anchored zoom, left-drag = select a range (the ledger filters to it), right-click = clear/pan, search box dims non-matching events
• Two projections — time (real duration; stalls are visible) and sequence (one slot per event; long sessions stay readable)
• Light/dark aware, zero external resources, works from file://

Trajectory pages always render the full timeline: --depth/--detail/--compact variants don't apply (they're normalized away with a warning). Incremental caching works as usual — unchanged sessions aren't re-rendered.

Sub-agent (sidechain) events appear in the same swimlanes and carry an agent tag in the tooltip and details panel.

opencode Provider (this fork)

--provider opencode renders session archives from opencode (stored under ~/.local/share/opencode/):

# All opencode sessions, grouped into projects by working directory
claude-code-log-trajectory --provider opencode --open-browser

# Both HTML flavours for opencode too
claude-code-log-trajectory --provider opencode -f html,trajectory

# One session
claude-code-log-trajectory --provider opencode --session-id ses_xxxx

• Reads the current SQLite storage (opencode.db, opened read-only) and falls back to the legacy JSON storage (storage/session|message|part/) for pre-migration sessions
• Maps opencode's message/part model onto the normal rendering pipeline: text, reasoning (as thinking), tool calls + results (with errors), per-message token usage
• Sub-agent child sessions are inlined into their parent as sidechains, so they show up in per-session pages and trajectory swimlanes
• Works with every output format: html, trajectory, md, json (and any comma-separated combination)

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 --detail low or minimal where tool stripping creates runs of Assistant or User sections

Installation

Install using pip:

pip install claude-code-log-trajectory

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

uvx claude-code-log-trajectory

Or install from source:

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

The package installs two console scripts: claude-code-log-trajectory (primary) and claude-code-log (compatibility alias — don't install this fork and the upstream claude-code-log package into the same environment, the alias would collide; uvx runs are isolated and unaffected).

Looking for the original tool without the trajectory/opencode additions? Install claude-code-log.

Environment Variables

Archive locations follow each tool's own override, so isolated / headless environments are found automatically:

Variable	Affects	Meaning
CLAUDE_CONFIG_DIR	claude	Claude Code's config home; sessions are read from $CLAUDE_CONFIG_DIR/projects/ (default ~/.claude/projects/). settings.json (e.g. cleanupPeriodDays) is read from the same dir.
CODEX_HOME	codex	Codex home; rollouts are read from $CODEX_HOME/sessions/ (default ~/.codex/sessions/).
XDG_DATA_HOME	opencode	opencode data dir; sessions are read from $XDG_DATA_HOME/opencode/ (default ~/.local/share/opencode/).

Headless runs (claude -p, codex exec, opencode run) persist sessions to these same locations by default, so they render like any other session. If a headless run left nothing behind, its persistence was disabled at the source — e.g. codex exec --ephemeral, Claude's --no-session-persistence / CLAUDE_CODE_SKIP_PROMPT_HISTORY / cleanupPeriodDays: 0, or opencode's OPENCODE_DB=:memory:.

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 conversation libraries? Or WASM?)
• add special formatting for built-in tools: Glob, Grep, LS, MultiEdit, NotebookRead, NotebookEdit, WebFetch, TodoRead, WebSearch
• 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
• 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
• add minimalist theme and make it light + dark; animate gradient background in fancy theme
• do we need special handling for hooks?
• make processing parallel, currently we only use 1 CPU (core) and it's slow
• merge git worktree directories