claude-replay
Turns AI coding agent sessions into self-contained, embeddable interactive HTML replays that are easy to share.
Evidence shows the tool reads local session files only, the editor binds to 127.0.0.1, Docker examples mount sessions read-only, secret redaction is on by default replacing matches with [REDACTED] before export, and a Privacy section discloses that full transcripts are embedded. Deductions: rollback is unaddressed (extract gives a round-trip but no export-undo concept, scored 1); source code (src/bin/test) is absent so minimal-privilege implementation and the localhost-only claim cannot be statically confirmed — least_privilege, user_confirmation, data_flow_transparency, external_effects scored 2. dependency_security earns 3: zero runtime dependencies, all GitHub Actions pinned by SHA, npm publish with provenance.
Zero runtime dependencies with engines Node 18+, CI testing 18/20/22/24 matrix gives dependency_availability 3. README is broadly consistent with package. (package description lists only Claude/Cursor/Codex, omitting newer sources — minor inconsistency, self_consistency 2). Source is missing so CLI failure-message quality cannot be verified; failure_messages scored 1.
Blog posts, docs, demos, bug reports, teaching, live monitoring scenarios are explicitly covered — audience_and_scenarios 3. Environment fit is thorough: Node version differences (node:sqlite needs 22.5+), Docker, browser support for DecompressionStream with --no-compress fallback, per-source format caveats — environment_fit 3. Capability boundaries partially covered (redaction is best-effort, Cursor lacks timestamps, Codex encrypted reasoning skipped) — 2. Session-ID auto-search precision cannot be verified in the provided files — trigger_precision 2.
Install notes (npm/npx/Docker), rich examples matching the options table, and a complete MIT license consistent with README badges earn 3s. Deductions: CHANGELOG is referenced in CI but the file itself is not in evidence; version 0.11.0 has no visible changelog — versioning_changelog 1. Repository structure can only be inferred from README/CI since src and tests are missing — information_architecture 2; maintenance_responsibility 2 (CI includes lint, multi-version tests, e2e, scheduled format-drift checks — positive signals but not fully verifiable). No FAQ; known_limitations partially documented — 2.
Self-contained HTML output, iframe embedding, and an extract round-trip command — output_usability 3. Converting multi-agent session logs into shareable replays is a clear differentiated value — marginal_value 3. Cost-benefit is reasonable overall (zero deps, compressed output), but replays embed the full transcript, can be large, and require manual review before sharing — cost_benefit 2.
README claims (format mappings, 60-70% compression, fallback behavior) have corresponding verification steps in CI — claim_traceability 2. README, package., LICENSE, and CI corroborate each other largely — cross_source_corroboration 2, with the npm description lagging README scope as a visible gap. Claims and inference are generally separated (e.g., the Brysbaert citation), but figures like compression rates lack independent support — fact_inference_separation 2. Source and test files were not provided, so implementations cannot be statically confirmed; hence overall confidence is low.
- Redaction is a best-effort pattern matcher and cannot catch every secret format; manually review generated HTML before public sharing.
- Replay files embed the full session transcript (source code, paths, tool I/O); exporting sessions from sensitive projects to untrusted audiences is risky.
- Publisher identity is unverified; verify npm provenance against the repository before installing.
- No CHANGELOG in evidence; review version differences before upgrading.
- Live watch mode continuously monitors session files; consider the exposure surface in shared or remote environments.
What does this agent do, and when should you use it?
claude-replay is an open-source CLI tool and web editor that reads on-disk session transcripts from Claude Code, Cursor, Codex CLI, Gemini CLI, OpenCode, Kimi Code, and Hermes Agent, auto-detects the format, and converts them into a single self-contained HTML replay file. The output embeds compressed transcript data inside a vanilla-JS player with no frameworks and no external requests, supporting play/pause, 0.5x–5x speed, block-by-block stepping, bookmarks and chapters, collapsible thinking/tool-call blocks, and a file activity sidebar. The tool automatically redacts common secret patterns (API keys, AWS credentials, JWTs, connection strings) before export and ships with multiple built-in and custom themes. It also offers a browser-based visual editor, iframe embedding, and a --serve --watch live monitoring mode. It requires Node.js 18+, has zero runtime dependencies, and can also be used via npx or Docker.
The tool searches ~/.claude/projects/, ~/.cursor/projects/, ~/.codex/sessions/, ~/.gemini/tmp/, ~/.kimi-code/sessions/, and Hermes SQLite stores (~/.hermes/state.db via node:sqlite on Node 22.5+) for session files and detects the format of each of the seven sources. The parser reads JSONL line by line (including Claude Code's streaming format), groups turns into user messages, assistant responses (text, tool calls, thinking blocks), and tool results, and maps foreign tool names to Claude Code equivalents for consistent rendering. The renderer deflate-compresses and base64-encodes the parsed turns and injects them into an HTML template; the player decompresses data in-browser via DecompressionStream. CLI commands include claude-replay (no args launches the web editor), claude-replay <input> -o replay.html (generate a replay, chaining up to 20 sessions), and claude-replay extract replay.html (pull embedded turn data back out for regeneration with different options).
- A technical blogger wants to show an AI-assisted coding session interactively instead of posting a bulky screen recording
- A documentation maintainer needs to embed an AI debugging session or code walkthrough into project docs via iframe
- A developer filing a bug report wants to attach a replayable session file instead of long logs
- An instructor teaching AI workflows needs to step through reasoning and tool usage turn by turn
- An engineer on a remote machine or container wants to monitor agent sessions live with --serve --watch
What are this agent's strengths and limitations?
- Zero runtime dependencies; output is a single self-contained HTML file you can email, host anywhere, or embed via iframe
- Auto-detects seven agent transcript formats and maps tool names across agents for consistent rendering
- Default automatic redaction of API keys, AWS credentials, JWTs, connection strings, and other secret patterns before export
- Web editor with live preview, --serve --watch live monitoring, and an extract command enabling full round-trip regeneration
- Custom themes via JSON (including arbitrary extraCss overrides) plus multiple timing modes (real timestamps or synthesized pacing)
- Replays embed the full transcript (source code, file paths, tool I/O, thinking traces); pattern-based redaction is best-effort, so public sharing requires manual review
- Editing the player JavaScript only affects rendering — the compressed data blob remains recoverable; sensitive turns must be excluded at generation time via CLI flags
- Browser decompression relies on DecompressionStream (Chrome 80+/Firefox 113+/Safari 16.4+); older browsers require --no-compress
- Cursor transcripts have no timestamps and only support synthesized paced timing; Codex encrypted reasoning blocks are skipped
- Reading live Hermes SQLite sessions requires Node 22.5+; older Node versions must export files first
How do you install or deploy this agent?
Install globally with npm: npm install -g claude-replay; or run without installing: npx claude-replay; or use Docker: docker run --rm --init -p 7331:7331 -v ~/.claude/projects:/root/.claude/projects:ro ghcr.io/es617/claude-replay. Requires Node.js 18+; reading live Hermes SQLite sessions requires Node 22.5+.
How do you use this agent?
Run claude-replay with no arguments to open the web editor (default port 7331), which auto-discovers Claude Code and Cursor sessions for browsing, editing, previewing, and exporting. Generate from the CLI: claude-replay <session-id or file path> -o replay.html, with options like --turns 5-15 to select turns, --speed 2.0 for playback speed, --theme dracula for theming, and --mark "5:Label" for bookmarks. Chain sessions: claude-replay abc123 def456 -o combined.html. Live preview: claude-replay session.l --serve --watch. Extract data from an existing replay to regenerate: claude-replay extract replay.html -o session.l.