simonw/claude-code-transcripts

claude-code-transcripts

Convert Claude Code session files (JSON or JSONL) to clean, mobile-friendly HTML pages with pagination.

Example transcript produced using this tool.

Read A new way to extract detailed transcripts from Claude Code for background on this project.

[!WARNING]

The web commands for both listing Claude Code for web sessions and converting those to a transcript are both broken right now due to changes to the unofficial and undocumented APIs that these commands were using. See issue #77 for details.

Installation

Install this tool using uv:

uv tool install claude-code-transcripts

Or run it without installing:

uvx claude-code-transcripts --help

Usage

This tool converts Claude Code session files into browseable multi-page HTML transcripts.

There are four commands available:

• local (default) - select from local Claude Code sessions stored in ~/.claude/projects
• web - select from web sessions via the Claude API
• json - convert a specific JSON or JSONL session file
• all - convert all local sessions to a browsable HTML archive

The quickest way to view a recent local session:

claude-code-transcripts

This shows an interactive picker to select a session, generates HTML, and opens it in your default browser.

Output options

All commands support these options:

• -o, --output DIRECTORY - output directory (default: writes to temp dir and opens browser)
• -a, --output-auto - auto-name output subdirectory based on session ID or filename
• --repo OWNER/NAME - GitHub repo for commit links (auto-detected if not specified). For web command, also filters the session list.
• --open - open the generated index.html in your default browser (default if no -o specified)
• --gist - upload the generated HTML files to a GitHub Gist and output a preview URL
• --json - include the original session file in the output directory

The generated output includes:

• index.html - an index page with a timeline of prompts and commits
• page-001.html, page-002.html, etc. - paginated transcript pages

Local sessions

Local Claude Code sessions are stored as JSONL files in ~/.claude/projects. Run with no arguments to select from recent sessions:

claude-code-transcripts
# or explicitly:
claude-code-transcripts local

Use --limit to control how many sessions are shown (default: 10):

claude-code-transcripts local --limit 20

Web sessions

Import sessions directly from the Claude API:

# Interactive session picker
claude-code-transcripts web

# Import a specific session by ID
claude-code-transcripts web SESSION_ID

# Import and publish to gist
claude-code-transcripts web SESSION_ID --gist

The session picker displays sessions grouped by their associated GitHub repository:

simonw/datasette              2025-01-15T10:30:00  Fix the bug in query parser
simonw/llm                    2025-01-14T09:00:00  Add streaming support
(no repo)                     2025-01-13T14:22:00  General coding session

Use --repo to filter the session list to a specific repository:

claude-code-transcripts web --repo simonw/datasette

On macOS, API credentials are automatically retrieved from your keychain (requires being logged into Claude Code). On other platforms, provide --token and --org-uuid manually.

Publishing to GitHub Gist

Use the --gist option to automatically upload your transcript to a GitHub Gist and get a shareable preview URL:

claude-code-transcripts --gist
claude-code-transcripts web --gist
claude-code-transcripts json session.json --gist

This will output something like:

Gist: https://gist.github.com/username/abc123def456
Preview: https://gisthost.github.io/?abc123def456/index.html
Files: /var/folders/.../session-id

The preview URL uses gisthost.github.io to render your HTML gist. The tool automatically injects JavaScript to fix relative links when served through gisthost.

Combine with -o to keep a local copy:

claude-code-transcripts json session.json -o ./my-transcript --gist

Requirements: The --gist option requires the GitHub CLI (gh) to be installed and authenticated (gh auth login).

Auto-naming output directories

Use -a/--output-auto to automatically create a subdirectory named after the session:

# Creates ./session_ABC123/ subdirectory
claude-code-transcripts web SESSION_ABC123 -a

# Creates ./transcripts/session_ABC123/ subdirectory
claude-code-transcripts web SESSION_ABC123 -o ./transcripts -a

Including the source file

Use the --json option to include the original session file in the output directory:

claude-code-transcripts json session.json -o ./my-transcript --json

This will output:

JSON: ./my-transcript/session_ABC.json (245.3 KB)

This is useful for archiving the source data alongside the HTML output.

Converting from JSON/JSONL files

Convert a specific session file directly:

claude-code-transcripts json session.json -o output-directory/
claude-code-transcripts json session.jsonl --open

This works with both JSONL files in the ~/.claude/projects/ folder and JSON session files extracted from Claude Code for web.

The json command can take a URL to a JSON or JSONL file as an alternative to a path on disk.

Converting all sessions

Convert all your local Claude Code sessions to a browsable HTML archive:

claude-code-transcripts all

This creates a directory structure with:

• A master index listing all projects
• Per-project pages listing sessions
• Individual session transcripts

Options:

• -s, --source DIRECTORY - source directory (default: ~/.claude/projects)
• -o, --output DIRECTORY - output directory (default: ./claude-archive)
• --include-agents - include agent session files (excluded by default)
• --dry-run - show what would be converted without creating files
• --open - open the generated archive in your default browser
• -q, --quiet - suppress all output except errors

Examples:

# Preview what would be converted
claude-code-transcripts all --dry-run

# Convert all sessions and open in browser
claude-code-transcripts all --open

# Convert to a specific directory
claude-code-transcripts all -o ./my-archive

# Include agent sessions
claude-code-transcripts all --include-agents

Development

To contribute to this tool, first checkout the code. You can run the tests using uv run:

cd claude-code-transcripts
uv run pytest

And run your local development copy of the tool like this:

uv run claude-code-transcripts --help