Skip to content

README.md

Latest commit

 

History

History
252 lines (173 loc) · 9.1 KB

README.md

File metadata and controls

252 lines (173 loc) · 9.1 KB

claude-code-transcripts

PyPI Changelog Tests License

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.

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 PATH|URL|OWNER/NAME - Git repo for commit links and code viewer. Accepts a local path, GitHub URL, or owner/name format.
  • --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
  • --code-view - generate an interactive code viewer showing all files modified during the session

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
  • code.html - interactive code viewer (when --code-view is used)

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

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 (also works with gistpreview.github.io for backward compatibility).

Large sessions: GitHub's gist API has size limits (~1MB). For large sessions, the tool automatically handles this:

  • Page content: When total page content exceeds 500KB, the tool generates separate page-data-NNN.json files for each page. The HTML pages are stripped of their inline content when uploaded, and JavaScript fetches the content from the JSON files on demand. This keeps each file small while preserving full functionality.

  • Code viewer: When using --code-view, large sessions may have a code-data.json file that also needs separate handling.

  • Two-gist strategy: When data files exceed 1MB total, they're uploaded to a separate "data gist", and the main gist's HTML files reference it.

  • Batched uploads: If files are still too large, they're automatically batched into multiple gists.

All of this happens transparently and requires no additional options. Search continues to work by fetching from the JSON files instead of HTML.

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

Code viewer

Use --code-view to generate an interactive three-pane code viewer that shows all files modified during the session:

# Generate with code viewer from a local session
claude-code-transcripts --code-view

# Point to the actual repo for full file content and blame
claude-code-transcripts --code-view --repo /path/to/repo

# From a URL
claude-code-transcripts json https://example.com/session.jsonl --code-view

The code viewer (code.html) provides:

  • File tree: Navigate all files that were written or edited during the session
  • File content: View file contents with git blame-style annotations showing which prompt modified each line
  • Transcript pane: Browse the full conversation with links to jump to specific file operations

When you provide --repo pointing to the local git repository that was being modified, the code viewer can show the complete file content with accurate blame attribution. Without a repo path, it shows a diff-only view of the changes.

Use --exclude-deleted-files to filter out files that no longer exist on disk:

claude-code-transcripts --code-view --exclude-deleted-files

This is useful when files were deleted after the session (either manually or by commands not captured in the transcript).

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 or URL directly:

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

# Fetch and convert from a URL
claude-code-transcripts json https://example.com/session.jsonl --open

When using Claude Code for web you can export your session as a session.json file using the teleport command.

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