README

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

This is a PHP port of claude-code-transcripts by Simon Willison.

Features

• Parse JSON and JSONL session files from Claude Code
• Generate paginated HTML transcripts (5 prompts per page)
• Render tool calls with syntax highlighting:
  • Write - File creation with content preview
  • Edit - Diff-style old/new display
  • Bash - Command display with description
  • TodoWrite - Task lists with status icons
  • Generic tool calls with JSON formatting
• Auto-detect GitHub repository for commit links
• Search functionality across all pages
• Mobile-friendly responsive design
• Batch conversion of all local sessions

Installation

Option 1: Download Static Binary (Recommended)

No PHP required. Download the pre-built binary for your platform:

# Linux x86_64
curl -fsSL https://github.com/kambo-1st/php-cc-transcripts/releases/latest/download/claude-code-transcripts-linux-x86_64 -o claude-code-transcripts
chmod +x claude-code-transcripts
sudo mv claude-code-transcripts /usr/local/bin/

# macOS Apple Silicon
curl -fsSL https://github.com/kambo-1st/php-cc-transcripts/releases/latest/download/claude-code-transcripts-macos-aarch64 -o claude-code-transcripts
chmod +x claude-code-transcripts
sudo mv claude-code-transcripts /usr/local/bin/

Option 2: Install with Composer (Global)

Requires PHP 8.1+.

composer global require kambo/cctranscripts

Make sure Composer's global bin directory is in your PATH:

# Add to your ~/.bashrc or ~/.zshrc
export PATH="$HOME/.composer/vendor/bin:$PATH"
# or for newer Composer versions:
export PATH="$HOME/.config/composer/vendor/bin:$PATH"

Then run:

claude-code-transcripts --help

Option 3: Install with Composer (Project)

Add to your project:

composer require kambo/cctranscripts

Run via vendor bin:

./vendor/bin/claude-code-transcripts --help

Option 4: Install from Source

git clone https://github.com/kambo-1st/php-cc-transcripts.git
cd php-cc-transcripts
composer install
./bin/claude-code-transcripts --help

Usage

Convert a single session file

claude-code-transcripts json /path/to/session.jsonl -o ./output

Options:

• -o, --output <dir> - Output directory (default: temp dir)
• --repo <owner/name> - GitHub repo for commit links (auto-detected if not specified)

Browse and convert local sessions

claude-code-transcripts local

This will scan ~/.claude/projects/ and let you select a session to convert.

Options:

• -o, --output <dir> - Output directory
• --limit <n> - Maximum sessions to show (default: 10)

Convert all sessions to archive

claude-code-transcripts all -o ./claude-archive

Creates a browsable archive with:

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

Options:

• -s, --source <dir> - Source directory (default: ~/.claude/projects)
• -o, --output <dir> - Output directory (default: ./claude-archive)
• --include-agents - Include agent-* session files
• --dry-run - Show what would be converted without creating files

Output Structure

Single session:

output/
├── index.html      # Overview with all prompts
├── page-001.html   # First 5 prompts
├── page-002.html   # Next 5 prompts
└── ...

Archive (all sessions):

claude-archive/
├── index.html              # Master index
├── project-name/
│   ├── index.html          # Project sessions list
│   ├── session-uuid/
│   │   ├── index.html
│   │   ├── page-001.html
│   │   └── ...
│   └── ...
└── ...

Programmatic Usage

<?php
require 'vendor/autoload.php';

use ClaudeCodeTranscripts\ClaudeCodeTranscripts;

$transcripts = new ClaudeCodeTranscripts();

// Convert a single session
$transcripts->generateHtml('/path/to/session.jsonl', './output');

// Convert with GitHub repo for commit links
$transcripts->generateHtml('/path/to/session.jsonl', './output', 'owner/repo');

// Find local sessions
$sessions = $transcripts->findLocalSessions($_SERVER['HOME'] . '/.claude/projects', 10);

// Generate batch archive
$stats = $transcripts->generateBatchHtml(
    $_SERVER['HOME'] . '/.claude/projects',
    './archive',
    false, // include agents
    function($project, $session, $current, $total) {
        echo "Processing $current/$total...\n";
    }
);

Building from Source

To build static binaries locally:

# Build for current platform (Linux)
./build.sh linux

# Build for macOS Intel
./build.sh macos

# Build for macOS Apple Silicon
./build.sh macos-arm

# Build all platforms
./build.sh all

Binaries will be created in the build/ directory.

License

Apache-2.0 (same as original project)

Credits

• Original Python version by Simon Willison
• PHP port created with Claude Code