claude-code-transcripts
Convert Claude Code session files (JSON/JSONL) to clean, paginated HTML transcripts with GitHub integration
How do I install this agent skill?
npx skills add https://github.com/reason-machines/claude-code-skills --skill claude-code-transcriptsIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill facilitates the export and sharing of Claude Code session histories. It requires access to sensitive local interaction logs and utilizes third-party dependencies to convert and upload data to GitHub.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
claude-code-transcripts
Skill by ara.so — Claude Code Skills collection.
Overview
claude-code-transcripts converts Claude Code session files (JSON or JSONL) into clean, mobile-friendly, paginated HTML transcripts. It supports local sessions from ~/.claude/projects, web sessions via the Claude API, and can publish directly to GitHub Gists for easy sharing.
Installation
Install using uv (recommended):
uv tool install claude-code-transcripts
Or run without installing:
uvx claude-code-transcripts --help
Install with pip:
pip install claude-code-transcripts
Key Commands
1. Local Sessions (Default)
Select from local Claude Code sessions stored in ~/.claude/projects:
# Interactive picker for recent sessions
claude-code-transcripts
# Explicitly use local command
claude-code-transcripts local
# Show more sessions
claude-code-transcripts local --limit 20
# Save to specific directory
claude-code-transcripts local -o ./my-transcript
# Auto-name output directory based on session
claude-code-transcripts local -a
# Include original JSON file
claude-code-transcripts local -o ./output --json
2. Web Sessions
Import sessions from Claude API (macOS automatically retrieves credentials from keychain):
# Interactive session picker
claude-code-transcripts web
# Import specific session by ID
claude-code-transcripts web SESSION_ABC123
# Filter by GitHub repo
claude-code-transcripts web --repo simonw/datasette
# Manually provide credentials (non-macOS)
claude-code-transcripts web --token $CLAUDE_TOKEN --org-uuid $ORG_UUID
3. Convert Specific JSON/JSONL Files
Convert a session file directly:
# From local file
claude-code-transcripts json session.json -o ./output
# From URL
claude-code-transcripts json https://example.com/session.json --open
# JSONL format (from ~/.claude/projects)
claude-code-transcripts json ~/.claude/projects/my-project/session.jsonl -a
4. Convert All Sessions to Archive
Create a browsable HTML archive of all local sessions:
# Default: converts all sessions to ./claude-archive
claude-code-transcripts all
# Preview without creating files
claude-code-transcripts all --dry-run
# Custom output directory
claude-code-transcripts all -o ./my-archive
# Include agent sessions (excluded by default)
claude-code-transcripts all --include-agents
# Open in browser when done
claude-code-transcripts all --open
# Quiet mode (errors only)
claude-code-transcripts all -q
Publishing to GitHub Gist
Upload transcripts to GitHub Gist and get a shareable preview URL:
# Requires: gh CLI installed and authenticated (gh auth login)
# From local session
claude-code-transcripts --gist
# From web session
claude-code-transcripts web SESSION_ID --gist
# From JSON file
claude-code-transcripts json session.json --gist
# Keep local copy too
claude-code-transcripts json session.json -o ./backup --gist
Output example:
Gist: https://gist.github.com/username/abc123def456
Preview: https://gisthost.github.io/?abc123def456/index.html
Files: /tmp/session-abc123
The preview URL uses gisthost.github.io to render the HTML gist with working relative links.
Common Options
All commands support these options:
-o, --output DIRECTORY- output directory (default: temp dir + auto-open browser)-a, --output-auto- auto-name subdirectory based on session ID/filename--repo OWNER/NAME- GitHub repo for commit links (auto-detected from git)--open- openindex.htmlin default browser (default when no-o)--gist- upload to GitHub Gist and output preview URL--json- include original session file in output directory
Output Structure
Generated files include:
output-directory/
├── index.html # Timeline of prompts and commits
├── page-001.html # First page of transcript
├── page-002.html # Second page of transcript
├── ...
└── session_ABC.json # Original session (if --json flag used)
Python API Usage
Use as a Python library:
from claude_code_transcripts.core import convert_session_to_html
from pathlib import Path
# Convert a session file
session_file = Path("~/.claude/projects/my-project/session.jsonl").expanduser()
output_dir = Path("./transcript")
convert_session_to_html(
session_file=session_file,
output_dir=output_dir,
repo="owner/repo", # Optional: for GitHub commit links
open_browser=True
)
Fetch web sessions programmatically:
from claude_code_transcripts.web import fetch_session_data, list_sessions
# List available sessions
sessions = list_sessions(token="...", org_uuid="...")
for session in sessions:
print(f"{session['id']}: {session.get('description', 'No description')}")
# Fetch specific session
session_data = fetch_session_data(
session_id="SESSION_ABC123",
token="...",
org_uuid="..."
)
Configuration
GitHub Repository Detection
The tool auto-detects the GitHub repository from your local git config. Override with --repo:
claude-code-transcripts --repo myorg/myrepo
This enables clickable commit links in the generated HTML.
Pagination
Transcripts are automatically paginated for readability. Each page includes:
- Navigation between pages
- Back to index link
- Timestamp for each message
- Syntax-highlighted code blocks
- Tool usage details
Common Patterns
Quick Preview Workflow
# Select recent session, generate HTML, and open in browser
claude-code-transcripts
Share Session Publicly
# Convert web session to Gist with one command
claude-code-transcripts web SESSION_ID --gist
Archive All Sessions
# Create complete browsable archive
claude-code-transcripts all -o ~/claude-archive --open
Backup with Source Data
# Keep both HTML and original JSON
claude-code-transcripts json session.json -o ./backup --json
Batch Processing
# Convert multiple sessions
for file in ~/.claude/projects/*/session.jsonl; do
claude-code-transcripts json "$file" -a -o ./all-transcripts
done
Troubleshooting
Web Sessions Not Working
Issue: web command fails to list/fetch sessions (currently broken - see issue #77)
Solution: Use local sessions or JSON exports instead:
# Use local sessions
claude-code-transcripts local
# Or export JSON from web UI and convert
claude-code-transcripts json exported-session.json
Gist Upload Fails
Issue: --gist option fails with authentication error
Solution: Install and authenticate GitHub CLI:
# Install gh CLI (macOS)
brew install gh
# Authenticate
gh auth login
Missing Commit Links
Issue: Commit hashes not linking to GitHub
Solution: Specify repository explicitly:
claude-code-transcripts --repo owner/repo
Or ensure you're in a git repository with GitHub remote:
git remote -v # Should show github.com URL
No Sessions Found
Issue: claude-code-transcripts local shows no sessions
Solution: Check Claude Code sessions directory:
ls -la ~/.claude/projects/*/session.jsonl
If empty, you may not have local sessions or they're stored elsewhere.
Large Session Files
Issue: Conversion takes a long time for very large sessions
Solution: Sessions are automatically paginated. For extremely large sessions, consider:
# Use quiet mode to suppress progress output
claude-code-transcripts json large-session.json -q
Environment Variables
While the tool doesn't require environment variables for most use cases, web API access may use:
CLAUDE_TOKEN- Claude API token (alternative to--token)ORG_UUID- Organization UUID (alternative to--org-uuid)
Note: On macOS, these are automatically retrieved from the system keychain when you're logged into Claude Code.
Examples
Example 1: Quick Local Session Export
# Interactive picker + auto-open
claude-code-transcripts
Example 2: Share Web Session
# Get shareable link
claude-code-transcripts web abc123def456 --gist
# Output:
# Gist: https://gist.github.com/user/xyz789
# Preview: https://gisthost.github.io/?xyz789/index.html
Example 3: Archive with Metadata
# Full archive with source files
claude-code-transcripts all \
-o ~/Documents/claude-sessions \
--include-agents \
--json \
--open
Example 4: Process URL
# Convert session from URL
claude-code-transcripts json \
https://raw.githubusercontent.com/user/repo/main/session.json \
-o ./transcript \
--repo user/repo \
--gist
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/reason-machines/claude-code-skills/claude-code-transcripts">View claude-code-transcripts on skillZs</a>