opencode-replay

opencode-replay

A CLI tool that generates static HTML transcripts from OpenCode sessions, enabling browsing, searching, and sharing of AI-assisted coding conversations.

Live Demo - See example session transcripts

Why?

OpenCode stores session data in ~/.local/share/opencode/storage/ as JSON files, but this data isn't easily browsable or shareable. opencode-replay transforms these sessions into clean, searchable, static HTML pages.

Use cases:

• PR Documentation - Attach session transcripts to pull requests showing the AI collaboration process
• Self-Review - Analyze past sessions to identify effective prompting patterns
• Team Sharing - Share session transcripts with teammates for knowledge transfer
• Debugging - Review what happened in a session when something went wrong
• Compliance - Maintain audit trails of AI-assisted code generation

Installation

# Using bun (recommended)
bun install -g opencode-replay

# Using npm
npm install -g opencode-replay

Quick Start

# Generate HTML for current project's sessions
cd /path/to/your/project
opencode-replay

# Open the generated transcript in your browser
opencode-replay --open

Output Formats

HTML (default)

Generate static HTML transcripts viewable in any browser:

opencode-replay                     # Current project's sessions
opencode-replay --all               # All projects
opencode-replay -o ./my-transcripts # Custom output directory
opencode-replay -a                  # Auto-name output (e.g., ./my-project-replay)

Markdown

Generate markdown for sharing or piping:

# To stdout (for piping)
opencode-replay -f md -s ses_xxx
opencode-replay -f md -s ses_xxx | gh gist create --filename transcript.md -
opencode-replay -f md -s ses_xxx | pbcopy

# To file
opencode-replay -f md -s ses_xxx -o transcript.md

GitHub Gist

Upload HTML directly to GitHub Gist with a shareable preview URL:

opencode-replay --gist                 # Secret gist (default)
opencode-replay --gist --gist-public   # Public gist
opencode-replay -s ses_xxx --gist      # Upload specific session

Requires GitHub CLI to be installed and authenticated (gh auth login).

The generated gist is viewable via gisthost.github.io which renders HTML files directly.

Usage

Basic Commands

# Generate HTML for current project (auto-detects from cwd)
opencode-replay

# Generate HTML for ALL projects across your machine
opencode-replay --all

# Specify output directory (default: ./opencode-replay-output)
opencode-replay -o ./my-transcripts

# Export a specific session by ID
opencode-replay --session ses_4957d04cdffeJwdujYPBCKpIsb

# Open in browser after generation
opencode-replay --open

# Include raw JSON export alongside HTML
opencode-replay --json

HTTP Server Mode

Serve generated transcripts via HTTP for easier viewing and sharing:

# Generate and serve via HTTP (default port: 3000)
opencode-replay --serve

# Serve on a custom port
opencode-replay --serve --port 8080

# Serve existing output without regenerating
opencode-replay --serve --no-generate -o ./existing-output

The built-in server includes:

• Automatic MIME type detection
• ETag-based caching for efficient reloads
• Directory index serving (serves index.html for directory requests)
• Path traversal protection
• Auto-opens browser on start

GitHub Integration

Add clickable links to GitHub commits in the rendered output:

opencode-replay --repo owner/repo-name

# Example
opencode-replay --repo sst/opencode

This adds links to commit hashes found in tool outputs, making it easy to navigate to the exact commits referenced during a session.

All Options

Option	Short	Description
--all		Generate for all projects (default: current project only)
--auto	-a	Auto-name output directory from project/session name
--output <path>	-o	Output directory (HTML) or file (markdown)
--session <id>	-s	Generate for a specific session only
--format <type>	-f	Output format: html (default), md
--stdout		Output to stdout (markdown only, requires --session)
--gist		Upload HTML to GitHub Gist after generation
--gist-public		Make gist public (default: secret)
--json		Include raw JSON export alongside HTML
--open		Open in browser after generation
--storage <path>		Custom storage path (default: ~/.local/share/opencode/storage)
--serve		Start HTTP server after generation
--port <number>		Server port (default: 3000)
--no-generate		Skip generation, only serve existing output
--repo <owner/name>		GitHub repo for commit links (e.g., sst/opencode)
--quiet	-q	Suppress non-essential output
--verbose		Show detailed debug output
--help	-h	Show help message
--version	-v	Show version

Examples

# Generate transcripts for your current project
cd ~/workspace/my-project
opencode-replay

# Generate all sessions and open in browser
opencode-replay --all --open

# Export a specific session with JSON data
opencode-replay --session ses_abc123 --json -o ./session-export

# Auto-name output from project name
opencode-replay -a  # Creates ./my-project-replay

# Use custom storage location
opencode-replay --storage /custom/path/to/storage

# Generate and serve for easy sharing
opencode-replay --serve --port 8080

# Quick preview of existing transcripts
opencode-replay --serve --no-generate -o ./my-transcripts

# Markdown to stdout for piping
opencode-replay -f md -s ses_xxx

# Create a GitHub Gist from a session
opencode-replay -s ses_xxx --gist

# Upload all projects to a public gist
opencode-replay --all --gist --gist-public

# Add GitHub commit links
opencode-replay --repo sst/opencode

Output Structure

opencode-replay-output/
├── index.html                    # Master index (all sessions)
├── assets/
│   ├── styles.css               # Stylesheet
│   └── search.js                # Client-side search
├── projects/                     # Only in --all mode
│   └── {project-name}/
│       └── index.html           # Project-level session list
└── sessions/
    └── {session-id}/
        ├── index.html           # Session overview with timeline
        ├── page-001.html        # Conversation pages (5 prompts each)
        ├── page-002.html
        └── session.json         # Raw data (if --json flag)

Tool Renderers

Each tool type has specialized rendering:

Tool	Display
bash	Terminal-style command with $ prefix, dark output box
read	File path header with content preview and line numbers
write	File path with "Created" badge, content preview
edit	Side-by-side diff view (old/new comparison)
glob	Pattern with file list and type icons
grep	Pattern with matching lines (file:line format)
task	Agent type badge with collapsible prompt/result
todowrite	Checklist with status icons
webfetch	Clickable URL with content preview
batch	Nested tool call summary

Requirements

• Bun runtime (recommended) or Node.js 18+
• OpenCode sessions in standard storage location
• GitHub CLI (optional, for --gist feature)

Development

# Clone the repository
git clone https://github.com/ramtinJ95/opencode-replay
cd opencode-replay

# Install dependencies
bun install

# Run in development mode
bun run src/index.ts

# Type check
bun run typecheck

# Build for distribution
bun run build

License

MIT