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.

Installation

Install this tool using uv:

uv tool install claude-code-transcripts

Or run the latest version from PyPI without installing:

uvx claude-code-transcripts --help

Running the forked version

If you have cloned this repository and want to run your local version:

1. Using uv run: Run the command from within the repository directory:

   cd claude-code-transcripts
   uv run claude-code-transcripts --help

2. Using uvx with the local directory: You can run the local version using uvx by pointing it to the current directory:

   uvx --from . claude-code-transcripts --help

3. Install as an editable tool: To install your local fork as a global tool that updates as you edit the code:

   uv tool install --editable .

   Now you can just run claude-code-transcripts from anywhere.

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 from git push output if not specified)
• --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

API Credentials

Automatic retrieval: API credentials are automatically retrieved from your system keyring if you've logged into Claude Code CLI. The tool works on:

• macOS: Uses macOS Keychain
• Linux: Uses system keyring (GNOME Keyring, KWallet, etc.)
• Windows: Uses Windows Credential Manager

To set up automatic credentials:

1. Install and run Claude Code CLI: https://claude.ai/code
2. Log in when prompted
3. Your credentials will be stored automatically

Manual credentials: If automatic retrieval doesn't work, you can provide credentials manually:

claude-code-transcripts web --token YOUR_TOKEN --org-uuid YOUR_ORG_UUID

To get your credentials manually:

1. Get your access token:

   • Open your browser's developer tools (F12)
   • Go to https://claude.ai
   • Navigate to Application > Local Storage > https://claude.ai
   • Copy the sessionKey value

2. Get your organization UUID:

   • In the same developer tools, go to the Network tab
   • Refresh the page and look for requests to api.claude.ai
   • Check the request headers for x-organization-uuid
   • Or find it in ~/.claude.json if you've used Claude Code before

If you encounter issues retrieving credentials, the tool will provide detailed instructions on how to obtain them.

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