Metadata-Version: 2.5
Name: claude-code-log-trajectory
Version: 1.6.0
Summary: Convert Claude Code transcript JSONL files to HTML, with a trajectory timeline view and opencode support (fork of claude-code-log)
Project-URL: Homepage, https://github.com/swchen44/claude-code-log-trajectory
Project-URL: Issues, https://github.com/swchen44/claude-code-log-trajectory/issues
Project-URL: Upstream, https://github.com/daaain/claude-code-log
Author-email: Daniel Demmel <hello@danieldemmel.me>, "Edward Z. Yang" <ezyang@mit.edu>, Shaowei Chen <swchen.tw@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: click>=8.3.0
Requires-Dist: dateparser>=1.2.2
Requires-Dist: gitpython>=3.1.52
Requires-Dist: jinja2>=3.1.6
Requires-Dist: mistune>=3.1.4
Requires-Dist: packaging>=25.0
Requires-Dist: pydantic>=2.12.0
Requires-Dist: pygments>=2.19.2
Requires-Dist: quickjs-ng<0.16,>=0.15.1.1
Requires-Dist: textual>=6.5.0
Requires-Dist: toml>=0.10.2
Description-Content-Type: text/markdown

# Claude Code Log Trajectory

**English** | [繁體中文](README.zh-TW.md)

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](https://github.com/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](https://opencode.ai) 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](https://github.com/user-attachments/assets/12d94faf-6901-4429-b4e6-ea5f102d0c1c)

TUI demo:

[TUI](https://github.com/user-attachments/assets/75718e2b-3b02-4e17-8f3d-366e2c40dcc2)

## Project Overview

📋 **[View Changelog](CHANGELOG.md)** - 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](https://swchen44.github.io/claude-code-log-trajectory/example/)** - 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](https://swchen44.github.io/claude-code-log-trajectory/example2/)** - 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:

```sh
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/`) — its `index.html` is what `--open-browser` opens
   - **Codex** (`~/.codex/sessions/`)
   - **opencode** (`~/.local/share/opencode/`)

   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:

```text
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):

```text
~/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:

```sh
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](https://opencode.ai) 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.

```bash
# 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)

```bash
# 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

```bash
# 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:

```bash
# 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`:

```bash
# 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:

```sh
~/.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:

```sh
# 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](https://opencode.ai) (stored under `~/.local/share/opencode/`):

```sh
# 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:

```bash
pip install claude-code-log-trajectory
```

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

```bash
uvx claude-code-log-trajectory
```

Or install from source:

```bash
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`](https://github.com/daaain/claude-code-log).

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and architecture documentation.

## Community Extensions

Projects built on top of `claude-code-log`:

- **[archive-session](https://github.com/lifeinchords/claude-code-skills#archive-session-skill--slash-command--optional-hook)** by [@lifeinchords](https://github.com/lifeinchords). Wraps the CLI as three integration surfaces:
  - a Claude Code [Skill](https://github.com/lifeinchords/claude-code-skills/blob/main/.claude/skills/archive-session/SKILL.md)
  - a Claude Code slash [Command](https://github.com/lifeinchords/claude-code-skills/blob/main/.claude/commands/archive-session.md) `/archive-session` for explicit in-chat invocation
  - a Claude Code PreCompact [Hook](https://github.com/lifeinchords/claude-code-skills/blob/main/.claude/hooks/pre-compact-archive.sh) 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](https://github.com/getbettr/octotail)
- wrap up CLI as Github Action to run after Cladue Github Action and process [output](https://github.com/anthropics/claude-code-base-action?tab=readme-ov-file#outputs)
- 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
