Claude Code를 위한 오픈소스 트레이스 뷰어 및 관측성 워크스페이스

Claude Code를 위한 오픈소스 트레이스 뷰어(trace viewer) 및 관측성(observability) 워크스페이스.

Claude Code의 .jsonl 세션을 재생(Replay)하고, 에이전트 흐름(agent flows)과 도구 호출(tool calls)을 검사하며, 토큰 급증(token spikes)을 포착하고, 실행 결과(runs)를 비교하여 실제로 어떤 일이 일어났는지 이해할 수 있습니다.

GitHub에서 Star 하기 · 데모 보기 · 빠른 시작 · 사용 사례 · 주요 기능 · 스크린샷 · 대상 사용자

90초 제품 데모 보기:

coding-log-analyzer-github-demo.mp4

Claude Trace Replay는 가공되지 않은 .jsonl 세션을 디버깅(debugging), 관측성(observability), 프롬프트 반복(prompt iteration)을 위한 재생 가능한 워크스페이스로 변환해 주는 오픈소스 Claude Code 트레이스 뷰어입니다.

대부분의 Claude Code 트레이스는 기술적으로는 풍부하지만 시각적으로 검토하기에는 매우 고통스럽습니다.

Claude Trace Replay는 가공되지 않은 세션 로그를 시각적 재생 및 디버깅 워크스페이스로 변환하여 다음과 같은 작업을 수행할 수 있게 합니다:

• 에이전트가 실제로 수행한 작업을 순서대로 확인
• 어떤 도구 호출(tool calls)이 시간, 토큰, 주의력(attention)을 소비했는지 이해
• 가공되지 않은 이벤트 블록을 읽는 대신 에이전트와 도구 간의 핸드오프(handoffs)를 재생
• 두 세션을 비교하여 프롬프트, 모델 또는 워크플로우 간의 차이점 파악
• 실행 후 프롬프트 품질 및 협업 패턴 검토

Claude Code를 진지하게 사용한다면, 이 도구는 여러분이 "트레이스를 캡처했다"는 단계에서 "무슨 일이 일어났는지 알고 있다"는 단계로 나아갈 수 있도록 도와줍니다.

노이즈가 많은 에이전트 실행 디버깅: 워크플로우가 느려지거나, 루프에 빠지거나, 작업에서 벗어난 정확한 턴(turn)을 찾으세요
도구 동작 검사: 파일 읽기, diff, 터미널 명령 및 도구 결과를 실행 순서대로 추적하세요
토큰 사용량 검토: 비용이 많이 드는 턴과 갑작스러운 급증을 일상화되기 전에 식별하세요
프롬프트 또는 모델 변경 사항 비교: 왜 하나의 Claude Code 세션이 다른 세션보다 성능이 더 좋았는지 확인하세요
팀과 학습 내용 공유: 가공되지 않은 트레이스를 사람들이 함께 검토할 수 있는 형태로 변환하세요

Agent Flow Replay (에이전트 흐름 재생): 메인 에이전트를 중심으로 호출 그래프 (call graph)가 단계별로 애니메이션화되는 과정을 지켜보세요
Current Step Context (현재 단계 컨텍스트): 최종 출력물뿐만 아니라 지금 당장 무엇이 일어나고 있는지 검사하세요
Searchable Timeline (검색 가능한 타임라인): 도구 호출 (tool calls), 생각 (thoughts), 차이점 (diffs), 파일 읽기 (file reads), 터미널 명령 (terminal commands) 및 결과를 탐색하세요
Token Analytics (토큰 분석): 비용이 많이 드는 턴 (turns)과 사용량 급증 구간을 빠르게 식별하세요
Session Compare (세션 비교): 메시지, 토큰, 도구 및 모델에 걸쳐 두 번의 실행 (runs)을 비교 (diff)하세요
AI Retrospective (AI 회고): 강점, 약점 및 다음 단계의 개선 사항을 도출하세요
Prompt Review (프롬프트 검토): 사후에 프롬프트 및 협업 품질을 검사하세요

• 노이즈가 많은 Claude Code 세션을 디버깅하는 개발자
• 많은 도구를 사용하는 긴 에이전트 실행을 검토하는 사람
• 왜 특정 프롬프트나 워크플로우가 다른 것보다 더 잘 작동했는지 이해하려는 팀
• 추측하는 대신 실제 AI 코딩 트레이스 (traces)로부터 배우고 싶은 모든 사람

세션 개요 (Session Overview)	토큰 사용량 (Token Usage)

세션 타임라인 (Session Timeline)	AI 분석 (AI Analysis)

대화 흐름 (Conversation Flow)	에이전트 흐름 (Agent Flow)

세션 비교 (Session Compare)	에이전트 흐름 어시스턴트 반환 (Agent Flow Assistant Return)

사용 중인 Claude Code .jsonl 트레이스를 가져와 몇 분 안에 로컬에서 여세요.

• Node.js 18+
• npm

git clone https://github.com/harrylettering/claude-trace-replay.git
cd claude-trace-replay
npm install

./start.sh

http://localhost:3000을 여세요.

.

npm run build

npm run preview

• 앱을 로컬에서 실행합니다.
• Claude Code .jsonl 트레이스를 로드합니다. - 타임라인, 토큰, 흐름, 비교 및 분석 뷰 사이를 이동합니다.
• 실행이 느려지거나, 노이즈가 발생하거나, 경로를 벗어난 정확한 단계를 찾습니다.

팁: 프로젝트를 공유할 계획이라면, 실제 트레이스를 사용하여 짧은 전/후 비교 영상을 녹화하는 것이 정적인 스크린샷만 보여주는 것보다 가치를 더 빠르게 설명할 수 있습니다.

뷰 (View)	학습 내용
세션 개요 (Session Overview)	토큰, 메시지, 모델, 지속 시간 및 도구에 대한 상위 수준 통계
...

Claude Code 세션은 길어질 수 있고, 도구 사용이 많으며, 원시 트레이스 데이터만으로는 감사 (audit)하기 어려울 수 있습니다.

이 프로젝트는 이러한 세션들을 검토 가능하게 만들기 위해 존재합니다:

• 디버깅 (debugging) 용
• 성능 튜닝 (performance tuning) 용
• 프롬프트 반복 (prompt iteration) 용
• 에이전트 워크플로우 학습 (agent workflow learning) 용
• 다른 사람과 실행 결과 (runs)를 공유 및 비교하는 용

Claude Trace Replay는 Claude Code의 .jsonl 세션 트레이스 (session traces)를 기반으로 구축되었습니다.

전형적인 엔트리 (entry) 유형은 다음과 같습니다:

user

assistant

system

• 도구 사용 (tool-use) 및 도구 결과 (tool-result) 콘텐츠 블록 (content blocks)
• 권한 (permission) 및 메타데이터 (metadata) 이벤트
• 파일 히스토리 스냅샷 (file history snapshots)

파서 (parser)에서 사용되는 일반적인 필드 (fields)에는 다음이 포함됩니다:

uuid

parentUuid

timestamp

type

message

isSidechain

isMeta

• React 18
• TypeScript 5
• Vite 5
• Tailwind CSS 3
• Recharts
• Framer Motion
• Lucide React
• html2canvas
• Zustand
• XYFlow / React Flow

claude-trace-replay/
├── docs/
│ └── screenshots/ # README 미디어 및 제품 비주얼
...

npm run dev # Vite 개발 서버 시작
npm run build # 타입 체크 및 프로덕션 빌드
npm run preview # 로컬에서 프로덕션 빌드 미리보기
...

• 처음 사용하는 사용자가 즉시 탐색할 수 있도록 익명화된 샘플 트레이스 (sample traces) 추가
• 대규모 세션의 성능 및 시각화 밀도 (visualization density) 개선
• 복잡한 에이전트 체인을 위한 더 많은 플로우 레이아웃 (flow layout) 모드 추가
• 보고서 및 회고 (retrospectives)를 위한 내보내기 프리셋 (export presets) 추가

기여 (Contributions)를 환영합니다.

좋은 기여 분야:

• 파서 (parser) 개선
• UI 다듬기 (UI polish)
• 대규모 트레이스에 대한 성능 작업
• 새로운 분석 패널 (analysis panels)
• 샘플 데이터셋 및 재현 가능한 버그 케이스

이 프로젝트가 Claude Code 세션을 더 빠르게 이해하는 데 도움이 되었다면, GitHub Star는 다른 사람들이 이 프로젝트를 찾는 데 큰 도움이 됩니다.

MIT