claude-replay

커뮤니티 도구 — Anthropic과 제휴하거나 승인받지 않았습니다.

AI 코딩 세션은 개발에 매우 유용하지만, 공유하기는 어렵습니다. 화면 녹화는 용량이 크고, 대화 기록(transcripts)은 탐색하기가 어렵습니다.

claude-replay는 Claude Code, Cursor, Codex CLI, Gemini CLI, 그리고 OpenCode 세션 로그를 대화형으로 공유 가능한 HTML 리플레이(replays)로 변환합니다. 생성된 리플레이는 외부 의존성이 없는 단일 독립형 HTML 파일입니다. 이 파일을 이메일로 보내거나, 어디든 호스팅하거나, 문서에 임베드(embed)할 수 있습니다. --serve --watch를 사용하여 에이전트 세션이 실행되는 동안 실시간으로 모니터링할 수 있습니다.

온라인에서 사용해보기 · 라이브 데모

Claude Code, Cursor, Codex CLI, Gemini CLI, 그리고 OpenCode는 대화 기록(transcripts)을 디스크에 저장합니다. claude-replay는 형식을 자동으로 감지하여 블로그 포스트, 데모, 문서에 적합한 시각적 리플레이로 변환합니다.

주요 기능 (Features)

• 독립형 HTML 출력 (의존성 없음)
• 속도 조절이 가능한 대화형 재생
• 도구 호출(tool calls) 및 사고 블록(thinking blocks, Claude의 내부 추론 흔적) 접기/펼치기
• 북마크 / 챕터
• 내보내기 전 비밀 정보 마스킹(redaction)
• 다양한 컬러 테마
• 터미널 스타일의 하단에서 상단으로의 스크롤
• 파일 활동 사이드바 — 어떤 파일이 수정되었는지 확인하고 해당 도구 호출로 이동
• iframe을 통한 임베드 가능
• 라이브 워치 모드 — 에이전트 세션을 실시간으로 모니터링 (--serve --watch)
• 시각적 세션 편집 및 미리보기를 위한 웹 기반 에디터 UI

사용 사례 (Use cases)

claude-replay는 다음과 같은 경우에 유용합니다:

• 블로그 포스트 (Blog posts) — AI 보조 개발 세션을 대화형으로 보여줌
• 문서화 (Documentation) — AI 디버깅 세션 또는 코드 워크스루 (Code walkthroughs)를 임베드함
• 데모 (Demos) — 비디오 없이 재현 가능한 세션을 공유함
• 버그 리포트 (Bug reports) — 긴 로그 대신 리플레이 (Replay)를 첨부함
• 교육 (Teaching) — AI의 추론 (Reasoning) 및 도구 사용 과정을 단계별로 살펴봄
• 실시간 모니터링 (Live monitoring) — 원격 머신이나 컨테이너에서 에이전트 (Agent) 세션을 실시간으로 관찰함

설치 (Installation)

npm install -g claude-replay

또는 npx를 사용하여 직접 실행 (설치 불필요):

npx claude-replay

Docker

docker run --rm --init -p 7331:7331 \
  -v ~/.claude/projects:/root/.claude/projects:ro \
  ghcr.io/es617/claude-replay

웹 에디터를 사용하려면 http://localhost:7331 을 엽니다. 세션 디렉토리는 읽기 전용 (Read-only)으로 마운트됩니다.

CLI 사용의 경우:

docker run --rm --init \
  -v ~/.claude/projects:/root/.claude/projects:ro \
  -v $(pwd):/output \
...

빠른 시작 (Quick start)

# 웹 에디터 실행 (기본값)
claude-replay

...

인자 없이 claude-replay를 실행하면 Claude Code 및 Cursor 세션을 자동으로 검색하는 브라우저 기반 에디터가 열립니다. 여기에서 리플레이를 시각적으로 탐색, 편집, 미리보기 및 내보낼 수 있습니다.

CLI 사용 시에는 세션 ID만 전달할 수 있습니다. claude-replay는 일치하는 파일을 찾기 위해 ~/.claude/projects/, ~/.cursor/projects/, ~/.codex/sessions/, 및 ~/.gemini/tmp/를 검색합니다. 또는 세션 파일의 전체 경로를 직접 전달할 수도 있습니다.

Cursor

Cursor 트랜스크립트 (Transcripts)도 지원되며, 형식은 자동으로 감지됩니다. Cursor 트랜스크립트에는 타임스탬프 (Timestamps)가 포함되어 있지 않으므로, 재생 시 기본적으로 조절된 타이밍 (Paced timing)을 사용합니다 (타이밍 모드 (Timing modes) 참조).

claude-replay ~/.cursor/projects/*/agent-transcripts/<id>/<id>.jsonl -o replay.html

Codex CLI

Codex CLI (OpenAI) 트랜스크립트 (transcripts) 또한 지원되며, 형식은 자동으로 감지됩니다. Codex 도구 호출 (exec_command, apply_patch)은 Claude Code의 상응하는 기능 (Bash, Edit/Write)으로 매핑되어 동일한 디프 (diff) 뷰와 명령 미리보기로 렌더링됩니다.

claude-replay ~/.codex/sessions/2026/03/12/rollout-<id>.jsonl -o replay.html

Gemini CLI

Gemini CLI 트랜스크립트 (transcripts) 또한 지원되며, 형식은 자동으로 감지됩니다. Gemini는 세션을 인라인 사고 블록 (thinking blocks) 및 도구 호출 (tool calls)을 포함한 단일 JSON 파일(JSONL 아님)로 저장합니다. 일관된 렌더링을 위해 도구 이름은 Claude Code의 상응하는 기능 (run_shell_command → Bash, read_file → Read 등)으로 매핑됩니다.

claude-replay ~/.gemini/tmp/<projectHash>/chats/session-<id>.json -o replay.html

세션 ID로 검색할 수도 있습니다:

claude-replay <session-id> -o replay.html  # ~/.gemini/tmp/를 자동으로 검색합니다

OpenCode

OpenCode 트랜스크립트 (transcripts)가 지원되며, 형식은 자동으로 감지됩니다. OpenCode는 세션을 SQLite 데이터베이스에 저장하므로, 먼저 OpenCode CLI를 사용하여 세션을 내보내야 합니다. 사고/추론 (Thinking/reasoning) 블록은 네이티브하게 렌더링됩니다.

# OpenCode에서 세션을 내보낸 후, 이를 재생합니다
opencode export <sessionID> > session.jsonl
claude-replay session.jsonl -o replay.html

웹 에디터 (Web Editor)

기본 제공되는 환경입니다. 인자 없이 claude-replay를 실행하여 시작할 수 있습니다:

claude-replay
claude-replay --port 8080

에디터에서 제공하는 기능:

• 세션 브라우저 (Session browser) — ~/.claude/projects/, ~/.cursor/projects/, ~/.codex/sessions/, ~/.gemini/tmp/에서 세션을 자동으로 검색하며, 다른 곳에 저장된 세션 파일을 위한 폴더 탐색기도 제공합니다.
• 턴 에디터 (Turn editor) — 턴(turn) 포함/제외, 사용자 프롬프트 편집, 어시스턴트 블록 확장 (읽기 전용), 북마크 추가
• 옵션 패널 (Options panel) — 테마, 속도, 사고/도구 호출 토글, 비식별화 (redaction) 규칙, 라벨
• 라이브 미리보기 (Live preview) — 편집 시 실시간 업데이트되며, CLI와 동일한 출력을 렌더링합니다.
• 내보내기 (Export) — 최종 HTML 재생 파일을 다운로드합니다.

에디터는 127.0.0.1에서 로컬 서버 (Local server)를 실행합니다 (localhost 전용이며, 네트워크에 노출되지 않음). 원본 JSONL 파일은 절대 수정하지 않습니다. 모든 편집 사항은 메모리(Memory)에 유지되며, 내보낸(Exported) 결과물에만 영향을 미칩니다.

사용법 (Usage)

claude-replay [--port N]                        웹 에디터 실행 (기본값)
claude-replay <input> [input2...] [options]     CLI로부터 재생 파일 생성
claude-replay extract <replay.html> [-o output.jsonl] [--format jsonl|json]

각 <input>은 세션 파일 경로 또는 세션 ID (Session ID)가 될 수 있습니다. 기존 파일 경로가 아닌 경우 세션 ID로 처리됩니다. claude-replay는 ~/.claude/projects/, ~/.cursor/projects/, ~/.codex/sessions/, 그리고 ~/.gemini/tmp/에서 일치하는 세션 파일을 검색합니다. Claude Code에서 /status를 실행하여 현재 세션 ID를 확인할 수 있습니다.

여러 개의 입력값은 하나의 재생 파일로 결합됩니다 (최대 20개). 모든 세션에 타임스탬프 (Timestamp)가 있는 경우, 턴 (Turns)은 시간 순서대로 정렬됩니다. 그렇지 않은 경우 명령줄(Command-line) 순서가 사용됩니다. 이는 계획(Plan)을 수락할 때 새로운 세션이 생성되는 경우에 유용합니다. 세션들을 체이닝(Chaining)하여 하나의 재생 파일에서 전체 과정을 확인할 수 있습니다.

명령어 (Commands)

editor [file|session-id]

웹 기반 재생 에디터를 실행합니다. 시작 시 파일을 자동으로 로드하려면 선택적으로 파일 경로 또는 세션 ID를 전달할 수 있습니다. 위의 웹 에디터 (Web Editor) 섹션을 참조하세요.

claude-replay editor                              # 빈 에디터 실행
claude-replay editor ~/.claude/projects/.../session.jsonl  # 파일 자동 로드
claude-replay editor abc123                       # 세션 ID로 자동 로드

extract

이전에 생성된 재생 HTML 파일에서 내장된 턴 (Turn) 데이터를 추출합니다. 기본적으로 JSONL 형식(한 줄당 하나의 턴, 북마크 포함)으로 출력합니다. 레거시(Legacy) JSON 형식을 사용하려면 --format json을 사용하세요.

claude-replay extract replay.html -o session.jsonl            # JSONL (기본값)
claude-replay extract replay.html -o data.json --format json  # JSON

추출된 JSONL 파일은 다른 옵션을 사용하여 다시 생성하기 위해 claude-replay에 다시 입력될 수 있습니다. 북마크(Bookmarks)는 각 턴(turn)의 bookmark 필드로 보존됩니다.

옵션 (Options)

예시 (Examples)

# 5번째부터 15번째 턴을 2배속으로 재생
claude-replay session.jsonl --turns 5-15 --speed 2.0 -o replay.html

...

타이밍 모드 (Timing modes)

--timing 플래그는 재생 속도가 도출되는 방식을 제어합니다:

paced 모드는 프레젠테이션 스타일의 타이밍을 생성합니다. 이는 프레젠테이션에서 슬라이드가 나타나거나 비디오에서 자막이 맞춰지는 방식과 유사합니다. 블록(block)이 공개되는 속도는 텍스트 길이에 따라 조절됩니다. 이는 타임스탬프가 없는 Cursor 트랜스크립트(transcripts)의 기본값이며, 더 부드러운 데모를 위해 Claude Code 트랜스크립트에서도 사용할 수 있습니다:

# Claude Code 트랜스크립트에도 paced 타이밍 사용
claude-replay session.jsonl --timing paced -o demo.html

플레이어 컨트롤 (Player controls)

생성된 HTML 파일은 완전히 독립적인 대화형 플레이어입니다:

• 재생/일시정지 (Play/Pause) — 블록 단위 애니메이션과 함께 턴(turns)을 자동으로 진행합니다.
• 앞으로/뒤로 단계 이동 (Step forward/back) — 턴 내에서 한 번에 하나의 블록씩 탐색합니다.
• 진행 바 (Progress bar) — 클릭하여 원하는 시점으로 점프할 수 있으며, 세션 타이머가 경과 시간/총 시간을 표시합니다.
• 속도 제어 (Speed control) — 0.5배속에서 5배속까지 재생 속도 조절이 가능합니다.
• 체크박스 토글 (Toggle checkboxes) — 생각 블록(thinking blocks)과 도구 호출(tool calls)을 표시하거나 숨깁니다.

키보드 단축키 (Keyboard shortcuts)

테마 (Themes)

내장 테마 (Built-in themes)

claude-replay --list-themes

사용 가능한 테마: tokyo-night (기본값), monokai, solarized-dark, github-light, dracula, bubbles.

커스텀 테마 (Custom themes)

CSS 색상 값을 포함한 JSON 파일을 생성하세요:

{
  "bg": "#0d1117",
  "bg-surface": "#161b22",
...

claude-replay session.jsonl --theme-file my-theme.json -o replay.html

누락된 키는 tokyo-night 기본값으로 채워지므로, 변경하고 싶은 색상만 지정하면 됩니다.

고급 사용자 정의(Advanced customization)를 위해, 레이아웃, 글꼴 또는 기타 스타일을 재정의할 수 있는 임의의 CSS 규칙이 담긴 extraCss 키를 추가할 수 있습니다:

{
  "bg": "#ffffff",
  "text": "#1c1e21",
...

extraCss를 사용하여 완전히 사용자 정의된 레이아웃을 사용하는 예시는 내장된 bubbles 테마를 참조하세요.

임베딩 (Embedding)

출력물은 외부 의존성이 없는 단일 HTML 파일입니다. iframe을 사용하여 블로그 게시물이나 문서에 임베딩할 수 있습니다:

<iframe src="replay.html" width="100%" height="600" style="border: 1px solid #333; border-radius: 8px;"></iframe>

작동 원리 (How it works)

1. **파서 (Parser)**가 JSONL 트랜스크립트(transcript)를 한 줄씩 읽으며, Claude Code의 스트리밍 형식(단일 어시스턴트 메시지가 점진적인 콘텐츠 블록과 함께 여러 줄로 나타나는 형식)을 처리합니다.
2. 턴(Turns)은 다음과 같이 그룹화됩니다: 사용자 메시지 + 어시스턴트 응답 (텍스트, 도구 호출 (tool calls), 사고 블록 (thinking blocks)) + 도구 결과 (tool results)
3. **렌더러 (Renderer)**는 파싱된 턴을 압축(deflate + base64)하여 HTML 템플릿에 주입합니다.
4. **플레이어 (player)**는 바닐라 JS (vanilla JS)로 작성되었습니다. 프레임워크나 외부 요청이 없습니다. 데이터는 로드 시점에 브라우저 네이티브 DecompressionStream API를 사용하여 압축을 해제합니다.

출력 최적화 (Output optimization)

생성된 HTML 파일은 두 단계의 최적화(외부 의존성 제로)를 사용합니다:

• Minified CSS/JS — 플레이어 템플릿은 esbuild로 미니파이(minified)됩니다 (변수 이름 난독화, 공백 제거). 읽기 가능한 출력을 원하면 --no-minify를 사용하세요.
• 압축된 데이터 (Compressed data) — 트랜스크립트 JSON은 deflate 방식으로 압축되고 base64로 인코딩되어, 일반적으로 출력 크기를 약 60-70% 줄여줍니다. 브라우저는 로드 시점에 DecompressionStream을 사용하여 네이티브하게 압축을 해제합니다 (Chrome 80+, Firefox 113+, Safari 16.4+). 오래된 브라우저의 경우 --no-compress를 사용하여 원본 JSON을 임베딩하세요.

개발 (Development)

template/player.html을 수정한 후 압축된 (minified) 템플릿을 다시 빌드하려면 다음을 실행하세요:

npm install    # esbuild (devDependency) 설치
npm run build  # template/player.min.html 생성

압축된 템플릿은 CI에서 빌드되어 npm 릴리스에 포함됩니다. 이 파일이 없으면 CLI는 자동으로 압축되지 않은 템플릿을 사용합니다.

비밀 정보 마스킹 (Secret redaction)

기본적으로 claude-replay는 임베딩된 모든 텍스트를 스캔하여 일반적인 비밀 정보 패턴을 찾아내며, 출력 HTML에 기록되기 전에 이를 [REDACTED]로 교체합니다. 이는 세션의 비밀 정보(API 키, 토큰, 연결 문자열 등)가 생성된 파일에 절대 포함되지 않음을 의미합니다.

감지된 패턴은 다음과 같습니다:

• API 키 (sk-..., sk-ant-..., key-...)
• AWS 액세스 키 ID (AKIA...)
• Bearer 및 JWT 토큰
• 데이터베이스 연결 문자열 (postgres://..., mongodb://... 등)
• 개인 키 블록 (-----BEGIN ... PRIVATE KEY-----)
• 일반적인 키/값 비밀 정보 (api_key=..., auth_token: ...)
• 환경 변수 비밀 정보 (PASSWORD=..., TOKEN=...)
• 긴 16진수(hex) 토큰 (40자 이상)

중요: 패턴 기반 마스킹은 최선의 노력을 다하는 안전망(safety net)일 뿐이며, 가능한 모든 비밀 정보 형식을 포착할 수는 없습니다. 공개적으로 공유하기 전에 항상 생성된 HTML을 검토하십시오.

마스킹을 비활성화하려면 (예: 내부용/개인용 플레이백의 경우):