ai-replay 0.4.2

Convert Claude Code, Cursor, and Codex CLI session transcripts to interactive HTML replays

ai-replay

Convert Claude Code, Cursor, Codex CLI, and OpenCode session transcripts to interactive HTML replays.

▶️ See a live demo — preview what a generated replay looks like before you install anything.

Python port of claude-replay by es617 (original JavaScript version).

Inspired by claude-code-transcripts by Simon Willison — the interactive session picker, --gist publishing flow, and output folder naming convention (<agent>-<sessionID>/index.html) are all modelled after his work.

Installation

uv tool install ai-replay

Usage

# Interactive session picker (default — runs when no arguments given)
ai-replay

# Generate HTML replay from a session file
ai-replay session.jsonl -o replay.html

# Generate from a session ID (auto-discovered)
ai-replay <session-id> -o replay.html

# Extract turns from a generated replay
ai-replay extract replay.html

# Serve replay on local HTTP server
ai-replay session.jsonl --serve --port 4000

OpenCode

OpenCode stores sessions in a SQLite database rather than on-disk JSONL files, so export a session to JSON first and pass the file to ai-replay (the format is auto-detected):

opencode export <sessionID> > session.json
ai-replay session.json -o replay.html

OpenCode's lowercase tool names (bash, read, write, edit, …) are mapped to their Claude Code equivalents so they render with the same diff views and command previews. Reasoning blocks render as thinking blocks.

Interactive picker options

ai-replay pick                  # explicit invocation
ai-replay pick --limit 30       # show more sessions (default: 20)
ai-replay pick --agent codex    # filter to one agent (partial match)

Options

• -o, --output FILE: Output HTML file (default: stdout)
• --title TEXT: Custom page title
• --theme NAME: Color theme (default: dark-knight)
• --no-redact: Disable automatic secret redaction
• --open: Open in browser after generating
• --no-compress: Embed raw JSON instead of compressed
• --serve: Serve on a local HTTP server
• --port INTEGER: Port for --serve (default: 4000)
• --turns TEXT: Turn range filter (e.g. "1-10")
• --exclude TEXT: Exclude specific turns (e.g. "3,7")

---

Development

Prerequisites

• Python 3.10+
• uv (recommended) or pip

Install the dev version from this branch

With uv (recommended):

# Clone the repo (or your fork)
git clone https://github.com/jeanclawd/ai-replay.git
cd ai-replay

# Check out the feature branch
git checkout feat/interactive-tui-picker

# Create a virtual environment and install in editable mode
uv venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
uv pip install -e .

# Verify
ai-replay --version

With pip:

git clone https://github.com/jeanclawd/ai-replay.git
cd ai-replay
git checkout feat/interactive-tui-picker

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .

# Verify
ai-replay --version

Run the tests

# With uv (inside the activated venv)
uv pip install pytest
pytest

# Or without activating:
uv run pytest

Expected output:

collected 6 items

tests/test_discover.py::test_discover_claude_and_codex PASSED
tests/test_discover.py::test_discover_agent_field PASSED
tests/test_discover.py::test_discover_limit PASSED
tests/test_discover.py::test_discover_summary_extraction PASSED
tests/test_discover.py::test_discover_no_sessions PASSED
tests/test_discover.py::test_discover_skips_agent_files PASSED

6 passed in 0.17s

Try the interactive picker

# Launch the TUI picker (requires Claude Code, Codex, or Cursor sessions on disk)
ai-replay

# Or explicitly:
ai-replay pick --limit 10

You should see an arrow-key menu like:

Loading sessions...
? Select a session to replay:
❯ Claude Code   2026-03-24 18:42    142 KB  Fix auth bug in middleware
  Codex         2026-03-23 11:10     98 KB  Add streaming support
  Cursor        2026-03-22 09:55    210 KB  Initial project scaffold

Select a session and it will:

1. Create <agent>-<sessionID>/ in your current working directory
2. Write the replay as index.html inside that folder
3. Open it in your browser

Output: ./claude-abc123def456/

The folder naming mirrors claude-code-transcripts — claude- for Claude Code, codex- for Codex, cursor- for Cursor.

Project structure

src/ai_replay/
├── __init__.py        # CLI entrypoint (click commands)
├── discover.py        # Session discovery across all agents  ← new in this branch
├── parser.py          # JSONL/JSON session parser
├── renderer.py        # HTML renderer
├── resolve_session.py # Resolve session ID → file path
├── secrets.py         # Secret redaction
└── templates/         # HTML templates
tests/
└── test_discover.py   # Discovery tests  ← new in this branch