Claude Code 트랜스크립트, 이렇게 뽑으면 프로젝트 퀄리티가 달라진다

Claude Code로 코드를 잔뜩 짜놓고 나면 이런 생각이 들 때가 있습니다.
"이거… 나중에 어떻게 다시 따라가보지?"

대부분의 결정, 시행착오, 프롬프트 실험이 전부 Claude Code 대화 안에 숨어 있기 때문이죠. 그런데 막상 그 기록을 꺼내 쓰려면 불편한 점이 한두 가지가 아닙니다.

이번 글에서는 그 문제를 꽤 우아하게 해결해주는 새로운 Python CLI 도구, claude-code-transcripts를 중심으로
“Claude Code에서 상세한 트랜스크립트를 추출하는 새로운 방법”들을 정리해보겠습니다¹.

마지막에는 /export, 다른 도구(Claude Code Exporter, 브라우저 확장)까지 비교해 어떤 상황에서 무엇을 쓰면 좋은지도 정리해 드릴게요.

Claude Code 트랜스크립트, 왜 이렇게까지 신경 써야 할까?

요즘 개발 흐름이 예전과 많이 달라졌습니다.
예전에는 기능 설계와 주요 결정이 이슈 트래커, PR 설명, 위키 페이지에 남았습니다.

지금은 어떤가요?

“이 기능 어떻게 설계하지?”
“이 버그는 왜 생겼지?”

이런 대화의 상당수가 Claude Code 세션 안에서 이뤄집니다.
심지어 많은 개발자가 휴대폰으로 산책하면서 Claude Code에 기능 하나를 통째로 구현시키기도 하죠¹.

문제는 이겁니다.

프로젝트의 맥락, 시행착오, 설계 이유가 전부 Claude 대화에 모여 있는데
이걸 다시 읽으려고 하면, 인터페이스가 길고 답답하고 검색도 불편하고
팀원에게 공유하려면 스크린샷 or 복붙 마라톤…

결국 “가장 중요한 기록”이 가장 활용하기 어려운 형태로 갇혀 있는 셈입니다.

그래서 나온 도구가 바로 claude-code-transcripts입니다.
Claude가 해준 “코딩 작업의 전체 타임라인”을 깔끔한 HTML 문서로 뽑아내,
나중에 내가, 혹은 팀이 다시 봐도 이해하기 쉬운 프로젝트 아카이브로 만들어 줍니다¹.

`claude-code-transcripts`란? 핵심 개념부터 정리

claude-code-transcripts는 Claude Code 대화 기록(JSON 세션 데이터)을 읽어, 구조화된 HTML 페이지로 변환해주는 Python CLI 도구입니다¹.

이 HTML이 그냥 텍스트 덤프가 아니라는 점이 포인트입니다.

첫 페이지는 요약/개요 페이지
“이 세션에서 무슨 작업을 했는지”를 한눈에 볼 수 있는 인덱스 역할을 합니다.
그 뒤에는 page_1.html, page_2.html … 이런 식의 상세 페이지가 이어지고
프롬프트, Claude의 응답, 코드 변경, 숨겨져 있던 “생각의 흐름”까지 촘촘하게 담깁니다¹.

게다가 이 도구는 두 가지 환경 모두를 지원합니다.

로컬 Claude Code (터미널/데스크톱)
Claude Code for web (비동기 웹 에이전트, iPhone 앱 등)¹

즉, “폰으로 시킨 작업”도 데스크톱에서 HTML로 깔끔하게 뽑아 볼 수 있다는 뜻입니다.

이제 “어떻게 쓰는지”를 실제 흐름에 맞춰 살펴볼까요?

설치 없이 시작해보기: uvx 한 줄로 HTML 트랜스크립트 만들기

이 도구의 매력 중 하나는 “깔끔한 진입 장벽”입니다.
Python 가상 환경, 패키지 설치 귀찮은 분들 많죠. 이미 uv를 쓰고 있다면 이렇게 시작할 수 있습니다¹.

uvx claude-code-transcripts

위 명령을 실행하면, CLI가 다음 흐름으로 진행됩니다.

첫째, 로컬 Claude Code 세션 목록이 뜹니다.
키보드의 방향키 위/아래로 원하는 세션을 고르고, Enter를 누릅니다¹.

둘째, 선택한 세션을 기반으로 새 폴더가 하나 생성됩니다.
그 안에는 대략 이런 구성의 파일들이 들어 있습니다.

index.html
→ 이 세션에서 어떤 프롬프트를 했고, 어떤 작업이 진행됐는지 핵심 요약
page_1.html, page_2.html, …
→ 한 단계씩 시간 순서대로, 실제로 무슨 일이 벌어졌는지 자세히 정리된 페이지들¹

셋째, 이렇게 만들어진 폴더를 그대로 정적 웹 호스팅에 올리거나,
폴더째로 압축해서 팀원에게 공유하거나, 개인 아카이브에 넣어두면 됩니다.

만약 아예 시스템에 도구를 설치해두고 싶다면 선택지는 세 가지입니다¹.

uv tool install claude-code-transcripts
# 또는
pip install claude-code-transcripts

설치 여부와 상관없이 중요한 건,
“몇 번의 키 입력만으로 Claude Code 세션 전체를 읽기 좋은 HTML로 뽑아낼 수 있다”는 점입니다.

GitHub Gist까지 자동 발행: `--gist` 옵션의 맛

트랜스크립트를 뽑았으면, 이제 공유가 문제입니다.

“이거 팀원들이랑 같이 보고 싶은데…”
“블로그 글에서 참고 링크로 걸고 싶은데…”

그럴 때 쓸 수 있는 옵션이 바로 --gist입니다.
전제 조건은 간단합니다. GitHub의 gh CLI가 설치되고, 로그인까지 돼 있어야 합니다¹.

이제 명령어를 이렇게 바꿔봅니다.

uvx claude-code-transcripts --gist

흐름은 아까와 거의 같습니다.

로컬 Claude Code 세션 목록이 뜹니다.
원하는 세션을 선택합니다.
이번에는 로컬 폴더만 만드는 게 아니라,
자동으로 GitHub Gist가 생성되고,
해당 HTML을 보기 위한 gistpreview.github.io 링크까지 함께 생성됩니다¹.

결과적으로,

“한 번의 명령으로 세션 선택”
“로컬 HTML 생성”
“Gist 발행 + 미리보기 링크 생성”

까지 작업이 한꺼번에 끝나므로,
“이 프로젝트 진행 과정을 공개적으로 공유하고 싶다”는 개발자에게 아주 편리한 워크플로우가 됩니다.

이 방식은 특히 이런 용도에 잘 맞습니다.

블로그/발표 자료를 만들 때, “전체 대화 기록”을 참고용 링크로 남기고 싶을 때
오픈소스 프로젝트에서 “이 기능은 이렇게 설계·구현했다”라는 히스토리를 공개하고 싶을 때
새로 합류한 팀원이 “이 기능 배경이 뭐냐”고 물을 때, 링크 하나만 던져주고 싶을 때

웹 버전 Claude Code 세션도 그대로 HTML로: reverse engineering의 힘

지금까지는 로컬 세션 기준이었고,
요즘 많은 사람이 Claude Code for web을 씁니다. 특히 iPhone 앱을 통해 비동기적으로 코딩 에이전트에게 일을 맡기는 경우가 많죠¹.

문제는 이 웹 세션의 트랜스크립트를 뽑기가 훨씬 까다롭다는 거였습니다.
그냥 브라우저에서 복붙하면 순서도 꼬이고, 숨겨진 생각 단계(thinking trace)도 빠집니다.

claude-code-transcripts는 이 부분도 해결했습니다.
개발자가 Claude Code의 웹용 비공개 API를 역설계해, 웹 세션 JSON을 직접 가져오는 방법을 찾아낸 겁니다¹.

사용자 입장에서는 명령 한 줄만 기억하면 됩니다.

uvx claude-code-transcripts web --gist

이 명령은 이렇게 동작합니다.

Claude Code for web 세션 목록을 불러옵니다.
원하는 세션을 선택하면
해당 세션이 HTML로 변환되고, 옵션에 따라 Gist로도 발행됩니다¹.

이때 내부적으로는 macOS Keychain에서 Claude Code의 OAuth 토큰을 꺼내 쓰는 기가 막힌 curl 패턴이 사용되었습니다.
이 아이디어 덕분에 사용자가 직접 API 키를 뒤지는 번거로움 없이, “이미 로그인된 상태”를 활용해 세션 목록을 가져올 수 있습니다¹.

정리하자면,

로컬 Claude Code
웹 버전 Claude Code

두 환경에서 만들어진 세션 모두를, 같은 툴로 일관된 HTML 형식으로 아카이빙할 수 있게 된 셈입니다.

기존 방법과 비교: `/export`, Claude Code Exporter, 브라우저 확장까지

그렇다면 “트랜스크립트를 추출하는 다른 방법들”과 비교했을 때,
claude-code-transcripts는 어떤 위치를 차지할까요?

1. Claude Code 내장 `/export` 기능

Claude Code에는 원래 간단한 내장 기능이 있습니다.
현재 대화 창에서 /export를 입력하면, 대화를 클립보드로 복사하거나 마크다운 파일로 저장할 수 있습니다².

장점은 명확합니다.

설치 필요 없음
지금 보고 있는 세션 한 건을 빠르게 저장 가능
마크다운 포맷이라 다른 도구로 2차 가공하기 좋음

하지만 한계도 있습니다.

세션 전체 타임라인을 “읽기 좋게 재구성”해주지는 않습니다.
요약 페이지, 단계별 상세 페이지 같은 구조화된 HTML이 아니라, 거의 “텍스트 덤프”에 가깝습니다.
여러 세션을 모아서 관리하거나 공유 링크를 자동으로 만들지는 않습니다.

“지금 이 대화만 빨리 저장해두고 싶다”면 /export가 최고지만,
“프로젝트 히스토리를 아카이브하고 싶은” 사람에게는 claude-code-transcripts가 훨씬 강력합니다.

2. Claude Code Exporter (Node.js / MCP 서버)

JavaScript·Node.js 환경을 선호한다면 Claude Code Exporter도 좋은 선택입니다³.

이 도구는 이런 특징을 갖고 있습니다.

Node.js 기반 CLI 및 라이브러리
~/.claude, ~/.config/claude 두 디렉터리 모두 지원
여러 프로젝트의 대화를 집계(aggregate) 해서 한 번에 추출 가능
기간 필터(7일, 30일, 3개월 등)와 기간별 그룹핑 지원
마크다운, JSON, 둘 다 동시에 내보내기 가능
MCP 서버로 실행하면 Claude Desktop과 직접 연동 가능

예를 들어, 최근 7일간 모든 프로젝트의 프롬프트만 모아서 보고 싶다면 다음처럼 쓸 수 있습니다³.

claude-prompts --aggregate --period=7d

“프롬프트 라이브러리 만들기”, “내가 어떤 질문을 자주 하는지 분석” 같은 용도에는 이 도구가 훨씬 잘 맞습니다.

대신,

HTML 기반의 “사람이 읽기 좋은 타임라인 뷰”는 claude-code-transcripts 쪽이 더 강점이고
Claude Code Exporter는 데이터 분석/집계와 마크다운·JSON 중심의 워크플로우에 최적화되어 있습니다.

두 도구는 경쟁 관계라기보다, “목적에 따라 골라 쓰는 도구”에 가깝습니다.

3. 브라우저 확장: Chat Export (Firefox)

웹에서 바로 버튼 한 번으로 대화를 저장하고 싶다면,
Firefox용 Chat Export 같은 확장도 있습니다⁴.

이 확장은 ChatGPT와 Claude 등 여러 LLM 사이트에서 대화를 추출해,
마크다운, HTML, XML, JSON 형식 중 하나로 내보내 줍니다⁴.

장점은 이렇습니다.

브라우저에서 바로 “Export” 버튼을 눌러 저장
설치 후 UX가 직관적이고 가벼움
여러 서비스(claude.ai, chat.openai.com 등)를 하나의 익숙한 인터페이스로 처리

반면, Claude Code만을 위한 “세션 단위 타임라인”, “프로젝트 맥락 중심의 HTML 페이지 구조” 같은 전문성은 없습니다.
일반 챗 세션 백업에는 최고지만, 코딩 에이전트의 전체 작업 히스토리를 복기하는 목적이라면 claude-code-transcripts가 훨씬 잘 맞습니다.

이 도구가 개발자에게 주는 실제 이득들

이제 “그래서 이걸 써서 뭐가 그렇게 좋은가요?”를 구체적인 상황으로 정리해보겠습니다.

첫째, 프로젝트 히스토리 복기가 쉬워집니다.
새 기능을 만들 때 어떤 제약 조건을 논의했는지, 왜 특정 설계를 선택했는지, Claude가 제안했던 대안은 무엇이었는지.
이 모든 맥락이 HTML 타임라인에 정리된 상태라, 나중에 “결정 이유”를 추적하기 훨씬 수월합니다¹.

둘째, 프롬프트 전략 연구에 큰 도움이 됩니다.
어떤 방식으로 지시했을 때 Claude가 더 좋은 코드를 작성했는지,
“이런 식으로 물어보면 실패한다” 같은 패턴이 눈에 보이기 시작합니다.
결과적으로, 프롬프트를 점점 더 잘 쓰게 됩니다.

셋째, 코드 리뷰 & 온보딩 도구로 활용할 수 있습니다.
새로 합류한 팀원에게 “이 기능은 여기서부터 이렇게 진화했다”고 보여줄 수 있고,
리뷰어도 단순히 최종 코드만 보는 대신 “문제 정의 → 아이디어 → 구현 → 리팩터링” 전체를 따라가 볼 수 있습니다.

넷째, 지식 자산화에 유리합니다.
이전에는 “머릿속”과 “채팅창”에만 있던 노하우가,
실제 파일로 남아 검색·공유 가능한 기록이 됩니다.
오픈소스든 사내 프로젝트든, 장기적으로 큰 차이를 만들어 내는 포인트입니다.

마무리: 어떤 상황에서 무엇을 쓰면 좋을까?

정리해보면, Claude Code 트랜스크립트를 추출하는 방법은 여러 가지가 있고, 각자 장단점이 뚜렷합니다.

“지금 이 대화만 빨리 저장하고 싶다”
→ Claude Code 내장 /export 사용 (클립보드/마크다운)²
“여러 프로젝트/기간에 걸친 프롬프트·응답을 모아서 분석하고 싶다”
→ Node.js 기반 Claude Code Exporter로 마크다운/JSON 집계³
“브라우저에서 간단히 Claude/ChatGPT 대화를 내보내고 싶다”
→ Firefox용 Chat Export 확장으로 HTML/Markdown/JSON/XML 저장⁴
“Claude Code가 수행한 전체 작업을, 읽기 좋은 HTML 타임라인으로 아카이브하고 공유하고 싶다”
→ Python CLI claude-code-transcripts가 가장 적합¹

개인적으로는 이렇게 조합하는 방식을 추천합니다.

개발 중에는
- 가벼운 백업은 /export
- 주간/월간 프롬프트 분석은 Claude Code Exporter
프로젝트가 어느 정도 마무리되면
- 핵심 Claude Code 세션은 claude-code-transcripts로 HTML 변환
- 필요하다면 --gist로 공개 링크까지 만들어,
  README나 블로그 글, 기술 문서에 “히스토리 링크”로 붙여두기

앞으로 “코드는 Git에 남고, 코딩 과정은 Claude에 남는” 시대가 본격화될수록,
이런 트랜스크립트 도구의 가치는 더 커질 것입니다.

어떤 도구부터 써볼지 고민 중이라면,
설치 부담이 적은 uvx claude-code-transcripts 한 줄로 시작해 보세요.
한 번 제대로 뽑힌 HTML 타임라인을 읽어보면,
“아, 이래서 다들 대화 기록을 아카이브하려고 하는구나”를 금방 느끼게 될 겁니다.

참고

¹A new way to extract detailed transcripts from Claude Code

²How to export current conversation in Claude Code

³Claude Code Exporter | MCP Servers · LobeHub