TalkReplay

The only tool that replays Claude, Codex, Cursor, AND Gemini sessions in one unified UI.

Unlike CLI tools that export static HTML, TalkReplay gives you a live, searchable interface to revisit AI pairing sessions, star important conversations, filter by date/keyword, and share insights with your team.

npx talk-replay

---

• Languages: English · 中文说明
• Providers: Claude, Codex, Cursor, Gemini — all in one place
• Tech stack: Next.js 14 · TypeScript · Tailwind CSS · Zustand
• Deploy anywhere: macOS, Windows, Linux, Docker, or npx

Why TalkReplay?

Vibe coding thrives on fast feedback loops. TalkReplay preserves that energy by:

• Ingesting local Claude/Codex sessions via pluggable adapters and a lightweight Node API
• Normalising timestamps/messages with provider metadata for consistent search and filters
• Providing a dual-pane explorer: session list on the left, detailed conversation on the right
• Tracking starred sessions, keyword filters, date ranges, and incremental refresh signatures
• Recording every collaboration round in agents_chat/ and enforcing hooks for reproducibility
• Demonstrating a vibe coding workflow end-to-end so you can mirror the structure in other projects

Vibe Coding Workflow

TalkReplay doubles as a living reference implementation for vibe coding teams:

• agents_chat/ captures each AI pairing session using timestamped Markdown that logs prompts, decisions, code excerpts, and self-tests.
• Husky pre-commit hook blocks commits unless a new log is staged and pnpm lint / pnpm test pass, preserving replayable histories.
• tasks.md tracks milestone checklists so incremental commits stay aligned with the agreed plan.
• Shared specs (agents.md, docs/) keep collaboration guardrails co-located with the codebase.

Interface Preview

More Screens

Getting Started (Local Dev)

pnpm install
pnpm dev -- --port 3002

Key scripts:

• pnpm lint – ESLint with Tailwind ordering
• pnpm test – Vitest + React Testing Library
• pnpm build – Next.js production build
• pnpm format:fix – Prettier write mode

On first run, a provider setup wizard appears and auto-detects common Claude/Codex/Cursor/Gemini directories; confirm or tweak the suggestions to start importing. You can revisit Settings at any point. Preferences persist via a safe localStorage wrapper that falls back to an in-memory store when quotas are exceeded.

One-command Preview (npx)

Install Node.js 18 or newer, then launch the prebuilt bundle directly from npm:

npx talk-replay --port 4000

Flags:

• --port / -p sets the listening port (defaults to 3000 or $PORT).
• --hostname / -H controls the bind address (0.0.0.0 by default for LAN access).
• --help prints usage details without starting the server.

The CLI ships with the Next.js standalone output, so no extra build step is needed when running via npx. When executing the CLI from a git checkout instead of npm, run pnpm build first to generate .next/standalone.

Service Installation (Auto-start)

Install TalkReplay as a system service to auto-start on login:

# Install and start the service
npx talk-replay install --port 3000

# Check status
npx talk-replay status

# Stop, start, restart
npx talk-replay stop
npx talk-replay start
npx talk-replay restart

# Remove the service
npx talk-replay uninstall

Install options:

• --port <number> – Port to listen on (default 3000)
• --hostname <value> – Hostname binding (default 0.0.0.0)
• --name <string> – Service name (default talk-replay)

Platform Details

macOS (launchd)

• Plist location: ~/Library/LaunchAgents/com.talkreplay.plist
• Logs: ~/Library/Logs/talk-replay.log
• The service starts automatically on login

Linux (systemd user service)

• Unit file: ~/.config/systemd/user/talk-replay.service
• View logs: journalctl --user -u talk-replay -f
• Requires systemd with user services enabled

Windows

• Requires node-windows package (optional dependency)
• Install it first: npm install -g node-windows && npm link node-windows
• Manage via Windows Services (services.msc)

Provider paths follow the same precedence as the web app (in-app settings → env vars → auto-detection). Supply overrides with environment variables when invoking npx:

NEXT_PUBLIC_CLAUDE_ROOT=$HOME/.claude/projects \
NEXT_PUBLIC_CODEX_ROOT=$HOME/.codex/sessions \
npx talk-replay --port 4500

Provider Roots & Configuration

Environment variables drive autodiscovery (defaults by OS):

NEXT_PUBLIC_CLAUDE_ROOT=/Users/you/.claude/projects   # macOS/Linux default
NEXT_PUBLIC_CODEX_ROOT=/Users/you/.codex/sessions     # macOS/Linux default
NEXT_PUBLIC_CURSOR_ROOT="/Users/you/Library/Application Support/Cursor" # macOS default
NEXT_PUBLIC_GEMINI_ROOT=/path/to/gemini/logs # optional

Windows paths

# PowerShell
$env:CLAUDE_ROOT="C:\\Users\\<you>\\.claude\\projects"
$env:CODEX_ROOT="C:\\Users\\<you>\\.codex\\sessions"
$env:CURSOR_ROOT="C:\\Users\\<you>\\AppData\\Roaming\\Cursor"
$env:NEXT_PUBLIC_CLAUDE_ROOT=$env:CLAUDE_ROOT
$env:NEXT_PUBLIC_CODEX_ROOT=$env:CODEX_ROOT
$env:NEXT_PUBLIC_CURSOR_ROOT=$env:CURSOR_ROOT

# Cmd
set CLAUDE_ROOT=C:\Users\<you>\.claude\projects
set CODEX_ROOT=C:\Users\<you>\.codex\sessions
set CURSOR_ROOT=C:\Users\<you>\AppData\Roaming\Cursor
set NEXT_PUBLIC_CLAUDE_ROOT=%CLAUDE_ROOT%
set NEXT_PUBLIC_CODEX_ROOT=%CODEX_ROOT%
set NEXT_PUBLIC_CURSOR_ROOT=%CURSOR_ROOT%

Linux/macOS paths

export CLAUDE_ROOT="$HOME/.claude/projects"
export CODEX_ROOT="$HOME/.codex/sessions"
export CURSOR_ROOT="$HOME/.config/Cursor"
export NEXT_PUBLIC_CLAUDE_ROOT="$CLAUDE_ROOT"
export NEXT_PUBLIC_CODEX_ROOT="$CODEX_ROOT"
export NEXT_PUBLIC_CURSOR_ROOT="$CURSOR_ROOT"

WSL2 note: use /mnt/c/Users/<you>/.claude/projects and /mnt/c/Users/<you>/.codex/sessions when launching Docker from WSL.

Server-side fallbacks honour CLAUDE_ROOT, CODEX_ROOT, CURSOR_ROOT, and GEMINI_ROOT. See src/config/providerPaths.ts for normalisation logic.

Automatic Defaults (No Settings/Env)

When neither Settings nor environment variables provide explicit paths, the server attempts to auto-detect provider roots from common locations. The first existing directory in the list below is used per provider.

• Claude defaults
  • Docker: /app/data/claude
  • macOS/Linux: ~/.claude/projects
  • Windows: C:\Users\<you>\.claude\projects (also tries ~/Documents/Claude/projects)
• Codex defaults
  • Docker: /app/data/codex
  • macOS/Linux: ~/.codex/sessions
  • Windows: C:\Users\<you>\.codex\sessions (also tries ~/Documents/Codex/sessions)
• Cursor defaults
  • macOS: ~/Library/Application Support/Cursor
  • Linux: ~/.config/Cursor
  • Windows: C:\Users\<you>\AppData\Roaming\Cursor
  • Docker: /app/data/cursor

Quick check: confirm Cursor ingestion with

pnpm dlx tsx scripts/check-cursor.ts \
  "/Users/<you>/Library/Application Support/Cursor"

• omit the argument to rely on CURSOR_ROOT / automatic defaults.
• Gemini (tentative; subject to change)
  • macOS/Linux: ~/.gemini/logs or ~/.gemini/sessions

Precedence

1. Settings (in-app) > 2. Environment variables (NEXT_PUBLIC_* for UI, CLAUDE_ROOT/CODEX_ROOT/GEMINI_ROOT for server) > 3. Automatic defaults

These defaults align with the Docker image’s volume layout and common CLI storage conventions, so most users can simply mount their local logs or let the app pick them up from ~.

Transcript Pipeline

• Provider ingestion lives under src/lib/providers/; adapters share a unified message schema in src/types/chat.ts.
• Incremental import signatures prevent reprocessing unchanged files while surfacing parser errors in the UI.
• Sample data in fixtures/ mirrors real directory layouts for Claude, Codex (Cursor coming soon), enabling offline demos.

Production Deployment

Option 1: Docker + Volume Mounts

Build and run the production bundle inside Docker:

docker build -t talk-replay .
docker run \
  -p 3000:3000 \
  -e NEXT_PUBLIC_CLAUDE_ROOT=/app/data/claude \
  -e NEXT_PUBLIC_CODEX_ROOT=/app/data/codex \
  -e NEXT_PUBLIC_CURSOR_ROOT=/app/data/cursor \
  -e CLAUDE_ROOT=/app/data/claude \
  -e CODEX_ROOT=/app/data/codex \
  -e CURSOR_ROOT=/app/data/cursor \
  -v "$HOME/.claude/projects":/app/data/claude:ro \
  -v "$HOME/.codex/sessions":/app/data/codex:ro \
  -v "$HOME/Library/Application Support/Cursor":/app/data/cursor:ro \
  talk-replay

Windows PowerShell

docker run `
  -p 3000:3000 `
  -e NEXT_PUBLIC_CLAUDE_ROOT=/app/data/claude `
  -e NEXT_PUBLIC_CODEX_ROOT=/app/data/codex `
  -e NEXT_PUBLIC_CURSOR_ROOT=/app/data/cursor `
  -e CLAUDE_ROOT=/app/data/claude `
  -e CODEX_ROOT=/app/data/codex `
  -e CURSOR_ROOT=/app/data/cursor `
  -v C:\Users\<you>\.claude\projects:/app/data/claude:ro `
  -v C:\Users\<you>\.codex\sessions:/app/data/codex:ro `
  -v C:\Users\<you>\AppData\Roaming\Cursor:/app/data/cursor:ro `
  talk-replay

WSL2 (from the Ubuntu shell)

docker run \
  -p 3000:3000 \
  -e NEXT_PUBLIC_CLAUDE_ROOT=/app/data/claude \
  -e NEXT_PUBLIC_CODEX_ROOT=/app/data/codex \
  -e NEXT_PUBLIC_CURSOR_ROOT=/app/data/cursor \
  -e CLAUDE_ROOT=/app/data/claude \
  -e CODEX_ROOT=/app/data/codex \
  -e CURSOR_ROOT