daaain/claude-code-log

A Python CLI tool that converts Claude Code transcript JSONL files into readable HTML / Markdown format.

Claude Code Log – 무엇인가요

Claude Code Log 는 Anthropic 의 Claude Code IDE 가 생성하는 JSONL 전사 파일을 깔끔하고 검색 가능한 HTML 페이지 또는 Markdown 문서로 변환하는 Python 명령줄 도구입니다. 단일 세션 파일부터 ~/.claude/projects/ 계층 구조 전체까지, Claude Code 와 나눈 모든 대화를 탐색, 필터링, 내보낼 수 있습니다.

왜 사용해야 할까?

과거 작업 검토 – 프롬프트, 어시스턴트 응답, 도구 호출, 토큰 사용량을 읽기 쉬운 타임라인으로 확인할 수 있습니다.
비용 인식 – 토큰 사용량 카운터로 각 세션(또는 전체 프로젝트)의 비용을 파악할 수 있습니다.
공유 및 아카이브 – 생성된 HTML 페이지는 브라우저에서 열거나 팀원과 공유할 수 있습니다.
검색 및 분석 – 날짜, 메시지 유형, 키워드로 필터링 가능; LLM 에서 패턴 인식에 활용할 수 있는 컴팩트한 Markdown 버전을 내보낼 수 있습니다.
라이브 모니터링 – watch 모드는 Claude 세션이 작성되는 동안 실시간으로 출력을 재생성하여 Obsidian 노트나 브라우저 뷰를 최신 상태로 유지합니다.

핵심 기능 (README 에 설명됨)

기능	기능 설명
인터랙티브 TUI	세션 탐색, 요약 보기, 키보드 단축키로 HTML/Markdown 내보내기 가능한 터미널 UI
Watch / Serve 모드	`claude-code-log watch` 는 파일을 실시간으로 업데이트; `serve --watch` 는 새 메시지 도착 시 자동 새로 고침하는 로컬 서버 실행
프로젝트 전체 처리	`~/.claude/projects/` 를 스캔하여 상위 레벨 인덱스 페이지와 프로젝트별 통합 전사본 생성
단일 파일 또는 디렉터리 변환	임의의 JSONL 파일 또는 폴더를 변환 가능; `--output` 로 출력 경로 지정
토큰 사용량 추적	메시지별 토큰 수와 세션/프로젝트별 총합 표시
런타임 필터링	HTML 내 JavaScript 컨트롤로 사용자, 어시스턴트, 시스템, 도구 사용 등을 숨기거나 표시 가능 (재빌드 없이)
시계열 정렬 및 타임라인	모든 메시지는 타임스탬프 순으로 정렬되며, 인터랙티브한 확대 가능한 타임라인으로 대화 흐름 시각화
테마	`classic` (기본) 및 `minimal` – 후자는 밀도 높은 라이트/다크 레이아웃으로 하위 에이전트의 접기 가능한 구조 지원
날짜 범위 필터링	자연어 날짜 (`today`, `last week`, `3 days ago`) 로 포함할 메시지 제한
풍부한 메시지 유형	사용자, 어시스턴트, 요약, 시스템 명령, 도구 호출/결과, 사고 단계, 내장 이미지 지원
Markdown 내보내기	서버 사이드 렌더링 및 구문 강조; `--detail` 및 `--compact` 플래그로 하위 LLM 분석용 컴팩트 버전 생성 가능
Git 커밋 링크	전사본 내 SHA 문자열을 감지해 GitHub/GitLab/Bitbucket 또는 사용자 정의 URL 템플릿으로 클릭 가능한 링크로 변환
프로바이더 훅	`--provider` 및 `--session-id` 를 통해 Antigravity CLI (`agy`) 및 Codex CLI (`codex`) 에 대한 실험적 지원 제공

누구를 위한 것인가요?

Claude Code 를 사용하고 대화 기록을 영구적이고 검색 가능한 아카이브로 원하는 개발자.
감사, 온보딩, 재현성을 위해 대화 로그를 공유해야 하는 팀.
여러 세션에 걸쳐 토큰 소비 또는 도구 사용 패턴을 분석하고자 하는 연구자 / 프롬프트 엔지니어.
정적 HTML 뷰나 컴팩트한 Markdown 덤프를 선호하여 다른 LLM 에 다시 입력하고자 하는 누구나.

시작하기 (README 에서의 빠른 시작)

# 영구 설치 없이 최신 버전 실행
uvx claude-code-log@latest --open-browser

이 명령어는 Claude Code 프로젝트 폴더를 스캔하고 HTML 아카이브를 생성한 후 기본 브라우저로 열립니다. 터미널 기반 경험을 원한다면 --tui 를 추가하세요.

설치 옵션

uv tool (권장): uv tool install claude-code-log
uvx (한 번 실행): uvx claude-code-log@latest
pip: pip install claude-code-log
소스에서: 리포지토리 복제 후 uv sync 실행, 이후 uv run claude-code-log 또는 uv tool install --editable . 로 편집 가능 설치

제한 사항 및 개선 사항 (TODO 에서)

아직 내장 튜토리얼 오버레이가 없음.
이미지 최적화 (예: PNG 스크린샷을 WebP 로 변환) 는 계획 중이나 구현되지 않음.
다른 Claude 관련 로그 (claude-trace, GitHub Action 출력) 와의 깊은 통합은 진행 중.
일부 UI 정교화 (그라데이션 애니메이션, 워크트리 병합) 는 로드맵에 있음.

결론

claude-code-log 는 Claude Code 의 원시 JSONL 전사본을 인간이 사용하기 쉬운 검색 가능한 아카이브로 변환하는 실용적이고 오픈소스 유틸리티입니다. TUI, 워치 모드, 테마 등 사용성에 중점을 두며, 개발자가 비용을 감사하고 작업을 공유하거나 과거 세션을 LLM 파이프라인에 다시 입력할 수 있는 데이터를 제공합니다.