Claude Code Trace: Claude Code 세션 로그 뷰어 및 Jev 기반 AI 에이전트 효율성 분석기

Claude Code Trace는 ~/.claude/projects/에 저장된 로컬 JSONL 파일을 위한 Claude Code 세션 로그 뷰어이자 Jev 기반 AI 에이전트 효율성 분석기입니다. 이 도구는 실시간 Claude Code 트레이스 관찰 가능성을 Jev(TypeSafe AI의 System One Model)를 통한 구조화된 행동 분석과 결합합니다. 사용자는 Claude Code 대화를 실시간으로 탐색, 테일링(tail), 검사할 수 있습니다. Claude Code Trace는 Claude Code JSONL 세션 파일을 확장 가능한 툴 호출, 토큰 카운트, 타임스탬프, MCP 툴 호출 감지 및 라이브 로그 테일링이 포함된 읽기 쉬운 대화 형태로 렌더링합니다. 선택적 Jev 통합 기능은 타입이 지정된 확률적 결정을 사용하여 에이전트의 진행 상황, 툴 사용, 집중도(focus), 탐색(exploration), 복구(recovery) 및 토큰 효율성을 점수화합니다. 이 도구는 macOS, Linux, Windows용 GUI 앱, 웹 앱 또는 TUI로 실행됩니다. Claude Code Trace는 Claude Code 에이전트 트레이스를 Jev를 위한 개인 정보 보호 검토가 완료되고 수정된 분석 요청으로 변환합니다. 그 결과로 생성되는 세션 효율성 대시보드는 반복 작업, 스래싱(thrashing), 과도한 탐색, 실패한 재시도, 효과적인 복구, 유용한 서브 에이전트 작업 및 비효율적인 토큰 사용을 식별하는 데 도움을 줍니다. 구조화된 Jev 결정은 생성된 산문 대신 타입이 지정된 확률을 사용하여 에이전트 행동을 평가합니다. 토큰 효율성 분석은 금전적 비용을 평가하지 않으면서 총 토큰, 컨텍스트 성장, 턴 수, 반복 작업 및 툴 활동을 고려합니다. 트레이스 연계 결과는 효율성 발견 사항에서 관련 Claude Code 메시지로 점프할 수 있게 합니다. 외부 분석 전 개인 정보 보호를 위해 정확히 수정된 페이로드(payload)를 보여주며 전송 전에 확인을 요구합니다. 보안 API 토큰은 Jev 및 제공업체 API 토큰을 macOS Keychain, Windows Credential Manager 또는 Linux Secret Service에 저장합니다. 버전별 로컬 결과는 세션당 최신 결과를 캐시하고 트레이스나 분석 공식이 변경될 때 이를 오래된(stale) 것으로 표시합니다.

통합 크레딧: Jev 기반의 Claude Code 분석 워크플로우는 delexw가 Claude Code Trace에서 설계하고 구축했습니다. Jev는 TypeSafe AI가 개발한 것으로, 이 오픈 소스 프로젝트는 독립적이며 TypeSafe AI의 공식 통합 기능이 아닙니다.

Claude Code Trace를 사용해야 하는 경우:

• ~/.claude/projects/에서 Claude Code 대화 기록을 확인하고 싶을 때
• 사용자 메시지를 통해 Claude Code 세션을 찾고 싶을 때
• Claude Code 도구 호출, MCP 호출, 타임스탬프 및 토큰 사용량을 검사하고 싶을 때
• Jev를 사용하여 Claude Code 에이전트 효율성을 분석하고 추적된 행동 발견 사항을 검토하고 싶을 때
• 실행 중인 라이브 Claude Code 세션을 모니터링하고 싶을 때
• 원시 JSONL 파일을 읽지 않고 장시간 실행되는 Claude Code 워크플로우를 디버깅하고 싶을 때
• DovePaw Lite와 같은 개인 AI 하네스 플랫폼을 지원하고 구축하고 싶을 때
• 데스크톱, 브라우저 또는 터미널 인터페이스에서 Claude Code 세션 로그를 탐색하고 싶을 때

Claude Code Trace는 또한 로컬 에이전트를 오케스트레이션하는 개인 AI 하네스 플랫폼인 DovePaw Lite를 지원하고 구축하는 데 사용됩니다. OpenAI Codex의 세션 뷰어인 Codex Trace도 확인해 보세요.

Claude Code JSONL 뷰어: ~/.claude/projects/에서 로컬 Claude Code 세션 파일을 읽습니다.
대화 브라우저: 원시 JSONL 로그를 스크롤 가능한 Claude Code 대화로 렌더링합니다.
라이브 테일링(Live tailing): 활성 Claude Code 세션을 실시간으로 모니터링합니다.
세션 검색: 사용자 메시지를 통해 세션을 찾습니다.
도구 호출 검사: 상세 디버깅을 위해 Claude Code 도구 호출을 확장합니다.
MCP 지원: Model Context Protocol(MCP) 도구 호출을 감지하고 사람이 이해하기 쉬운 이름으로 표시합니다.
토큰 가시성: Claude Code 세션 데이터에서 사용 가능한 토큰 수를 보여줍니다.
Jev 기반 효율성 분석: 추적된 발견 사항과 함께 진행률, 도구 사용, 집중도, 탐색, 복구 및 토큰 효율성을 점수화합니다.
데스크톱, 웹 및 TUI 모드: 워크플로우에 맞는 인터페이스를 선택할 수 있습니다.
교차 플랫폼 빌드: macOS, Linux 및 Windows를 지원합니다.

Claude Code는 로컬 세션 기록을 JSONL 파일로 저장합니다. 이 파일들은 AI 코딩 세션을 디버깅하고 검토하는 데 유용하지만, 직접 읽기는 어렵습니다. Claude Code Trace는 이러한 JSONL 로그를 인터랙티브한 세션 뷰어로 변환하여 사용자가 사용자 메시지별로 세션을 찾고, 대화를 검사하며, 도구 사용을 이해하고, Claude Code 워크플로우를 더 빠르게 디버깅할 수 있도록 합니다.

일반적인 관측성(observability) 플랫폼과 달리, Claude Code Trace는 로컬 Claude Code 세션 로그에 중점을 둡니다. 따라서 외부 서비스로 트레이스를 전송할 필요가 없습니다.

Claude Code Trace는 개인 AI 하네스 및 로컬 에이전트 플랫폼을 구축할 때 특히 유용합니다. 이는 Claude Code 세션을 검사하고, 도구 사용을 이해하며, DovePaw Lite와 같은 프로젝트를 구동하는 워크플로우를 디버깅하는 데 도움을 줍니다.

팁

클론(clone) 필요 없음. 빌드 도구 필요 없음. xattr 필요 없음. 터미널에 다음 명령어를 붙여넣으세요:

curl -fsSL https://raw.githubusercontent.com/delexw/claude-code-trace/main/script/install-macos.sh | bash

이 명령어는 최신 릴리스를 다운로드하고 Claude Code Trace.app을 /Applications에 설치하여 Spotlight에서 바로 열 수 있도록 준비합니다.

macOS는 다운로드된 것으로 표시된 서명되지 않은 앱을 차단하며, curl은 해당 플래그를 절대 설정하지 않기 때문에, 별도의 격리 해제(quarantine) 작업 없이 앱이 그냥 열립니다. 이것이 macOS 릴리스가 .app.tar.gz 형태이고 .dmg 형태가 아닌 이유입니다. Apple Silicon 전용입니다.

특정 버전을 고정하거나 다른 곳에 설치하려면 다음을 사용하세요:

curl -fsSL https://raw.githubusercontent.com/delexw/claude-code-trace/main/script/install-macos.sh \
| CCTRACE_VERSION=v0.15.1 CCTRACE_INSTALL_DIR=~/Applications bash

릴리스(Releases)에서 최신 릴리스를 가져가세요:

macOS에서는 위에 설명된 한 줄 설치 방법을 사용하세요. macOS 빌드를 수동으로 다운로드하는 것은 지원되지 않습니다. 앱이 서명되어 있지 않기 때문에, 브라우저가 다운로드한 모든 파일은 격리되고, 플래그를 직접 해제하기 전까지는 열지 않습니다.

이 옵션은 macOS, Linux 또는 Windows에 Rust와 Node.js가 설치되어 있을 때 Claude Code Trace를 로컬에서 구축하려는 경우 사용하세요.

git clone [email protected]:delexw/claude-code-trace.git
cd claude-code-trace
./script/install.sh # 모든 것을 빌드하고 PATH에 설치합니다
...

git clone [email protected]:delexw/claude-code-trace.git
cd claude-code-trace
npm install
...

Docker는 웹 모드에서만 지원됩니다.

대화형 배포를 위해서는 redeploy 스크립트를 사용하세요. 이 스크립트는 Jev API 키를 구성할지 업데이트할지 묻고, 에코(echo) 없이 읽은 후 실행 중인 컨테이너에 읽기 전용으로 마운트되는 Docker 관리 볼륨에 저장합니다:

./script/redeploy.sh

기존 Docker 키를 변경하지 않거나 Jev 분석 없이 실행하려면 No라고 답하세요.

대화형 프롬프트 없이 수동 배포를 하려면 다음을 사용하세요:

docker build -t claude-code-trace .
docker run --rm -p 1421:1421 \
-v "$HOME/.claude:/home/app/.claude:ro" \
...

또는 Docker Compose를 직접 사용하세요:

docker compose up --build

런타임 환경 변수, 볼륨 레이아웃 및 문제 해결에 대한 내용은 docs/docker.md를 참조하세요.

• Rust 1.88+

• Node.js 18+

• macOS: Xcode Command Line Tools (xcode-select --install)

• Linux:
  libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev libxdo-dev libssl-dev

• Windows: WebView2가 필요하며 Windows 10 및 Windows 11에 사전 설치되어 있습니다.

cctrace # 데스크톱 앱 (기본값)
cctrace --web # 웹 모드 (http://localhost:1420에서 브라우저 열림)
cctrace --tui # 터미널 UI (백엔드와 TUI를 함께 시작함)

Claude Code Trace를 실행하여 세션 피커를 엽니다. 이는 ~/.claude/projects/에서 Claude Code 세션을 자동으로 발견합니다.

.

세션을 선택하여 대화를 확인하세요. 메시지를 클릭하면 도구 호출(tool calls)이 확장되고, 상세 보기(detail view)를 열면 전체 검사가 가능합니다.

• 데스크톱 앱에서는 Settings → Analytics에서 Jev API 키를 운영 체제 자격 증명 저장소에 저장하고, 웹 모드에서는 JEV_API_KEY를 제공하세요.

서버 환경에서는 HTTP API가 의도적으로 API 토큰 저장 또는 삭제 요청을 허용하지 않습니다. TUI 역시 HTTP 클라이언트이므로 웹 모드와 동일하게 키를 읽어오며, 저장할 수 없습니다. - 선택
세션별 효율성 분석 (Analyse efficiency): TUI에서 세션 행에 a를 누르면, 동일한 분석 설정이 열립니다. - 로컬로 마스킹된 페이로드(payload)를 검토하고 전송되기 전에 명시적으로 확인하십시오.

• 효율성 대시보드와 추적 주석을 사용하여 Jev의 분석 결과를 검사합니다. TUI는 실시간 분석 진행 상황과 세션 행의 점수를 보여주며, 대시보드 자체는 데스크톱 및 웹에서만 사용 가능합니다.

기본 최소화 모드는 추출된 행동 신호(behavioural signals)와 선택된 발췌 내용을 전송합니다. 더 많은 컨텍스트가 필요할 때는 전체 스크립트(Full-transcript) 모드를 사용할 수 있습니다. 재분석은 해당 세션의 이전 결과를 대체하며, API 토큰은 설정 파일에 절대 기록되지 않습니다.

데스크톱 모드에서는 툴바에서 **브라우저에서 열기 (Open in Browser)**를 클릭하여 브라우저 모드로 전환할 수 있습니다. 이렇게 하면 기본 브라우저에서 http://localhost:1420이 열리고 데스크톱 창은 숨겨집니다.

만약 미리 빌드된 .app, .deb, 또는 .msi를 설치했다면, 바이너리에 --web을 전달하여 데스크톱 앱을 직접 실행할 수도 있습니다:

# macOS
/Applications/Claude\ Code\ Trace.app/Contents/MacOS/claude-code-trace --web

로컬 HTTP API(포트 11423)는 **승인된 클라이언트 (accepted clients)**만 응답합니다. 모든 호출자는 자체 서명 인증 정보(signed credential)를 제시하므로, 백엔드는 누가 요청하는지 알게 되며, 하나의 클라이언트를 비활성화해도 나머지는 영향을 받지 않습니다. 웹 UI와 TUI는 자동으로 등록됩니다 (web-ui, tui); 데스크톱 앱은 IPC를 통해 통신하며 아무것도 필요하지 않습니다. 설정 → 승인된 클라이언트에서 이를 나열하고 클라이언트를 추가, 재발급 또는 비활성화할 수 있습니다. 자체 스크립트의 경우, 여기에 클라이언트를 추가하고 인증 정보(한 번만 표시됨)를 복사하거나 TUI의 구성 디렉토리(~/.config/claude-code-trace; macOS: ~/Library/Application Support/claude-code-trace, Windows: %APPDATA%\claude-code-trace)에서 부트스트랩할 수 있습니다.

curl -H "X-CCTrace-Token: $(cat ~/.config/claude-code-trace/clients/tui.jwt)" \

Set CCTRACE_API_AUTH=off로 설정하여 검사를 비활성화할 수 있습니다.

참고: TUI는 기능하지만 사용자 경험(UX) 측면에서 몇 가지 미흡한 부분이 있습니다. 기여를 환영합니다.

MCP (Model Context Protocol) 도구 호출은 자동으로 감지되어 사람이 이해하기 쉬운 이름으로 표시됩니다.

예를 들어, mcp__chrome-devtools__take_screenshot는 요약(take screenshot)과 함께 MCP chrome-devtools로 렌더링됩니다.

지원되는 MCP 서버에는 chrome-devtools, figma, atlassian, buildkite, cloudflare 및 mcp__<server>__<tool> 명명 규칙을 따르는 기타 모든 서버가 포함됩니다.

?는 모든 보기에서 키 바인딩 힌트를 토글합니다.

npm install
npm run tauri dev # hot reload 기능이 있는 데스크톱 앱
npm run dev:web # 웹 모드, 데스크톱 창 없음
...

npm run check # 모든 검사 한 번에 실행
npx vitest run # 프론트엔드 테스트
npm run test:e2e # Playwright 엔드-투-엔드 테스트 (헤드리스 백엔드 + 웹 UI 빌드, Chromium 구동)
...

GitHub Actions 빌드를 트리거하려면 버전 태그를 푸시하세요:

git tag v0.4.0
git push origin v0.4.0

이렇게 하면 macOS, Linux 및 Windows 아티팩트가 첨부된 초안 릴리스가 생성됩니다. 릴리스 페이지에서 검토하고 게시하세요.

버그 보고서, 기능 요청, 그리고 풀 리퀘스트(pull request)는 환영합니다. 로컬에서 빌드하고 실행하는 방법은 'Development' 섹션을 참고하세요. 중대한 변경 사항의 경우, 먼저 이슈를 열어 범위를 조율하는 것이 좋습니다.