agent-trace-viewer

코딩 에이전트가 실제로 무엇을 했는지 봅니다 —
토큰, 비용, 도구 호출, 그리고 그 결과로 만들어진 PR과 파일.

로컬에서 실행하는 도구입니다. 내 컴퓨터에 이미 쌓여 있는 로그를 읽기 때문에, 이 페이지는 소개용이고 실제 화면은 각자 머신에서 띄웁니다. 로그가 외부로 나가지 않습니다.

왜 만들었나

Claude Code와 Codex는 모든 세션을 디스크에 완전히 기록합니다 — 프롬프트, 도구 호출과 그 원본 출력, 캐시 읽기를 포함한 모델별 토큰 사용량, 그리고 에이전트가 연 PR까지. 그런데 그걸 읽을 방법이 없습니다.

에이전트에 계측을 추가하지 않습니다. 이미 디스크에 있는 것만 읽습니다. 쿼터 미터가 아니라 다른 질문에 답합니다 — 그 많은 토큰이 어디로 갔는가.

기능

• 세션 목록 — 활동 시간, 토큰, 캐시 적중률, 도구 호출, 오류, 세션당 비용. 프로젝트별 필터.
• 세션 타임라인 — 사고 → 도구 호출 → 결과의 전체 사슬. 원본 인자와 출력을 펼쳐 보고, 단계별 출력 토큰과 다음 단계까지의 공백을 확인하고, 서브에이전트 트레이스로 파고듭니다. 4,600단계짜리 세션에서 오류는 스무 페이지에 흩어져 있어, 실패만 걸러 보는 필터가 필요합니다.
• 산출물 추적 — 그 세션이 연 PR과 실제로 바꾼 파일. 로그를 “작업 기록”으로 바꿔주는 부분입니다.
• 전문 검색 — 프롬프트·도구 인자·도구 출력을 가로질러 검색. 관련도 순 정렬과 하이라이트에서 해당 단계로 바로 이동.
• 집계 — 사용하는 에이전트 간 비교, 도구별 사용량과 실패율, 프로젝트별 지출과 캐시 적중률, 모델별 출력량.

숫자를 정직하게 다루는 방식

비용은 API 정가 환산이지 청구액이 아닙니다. 로그에는 토큰 수만 있고 과금 정보가 없습니다 — 종량제 키였는지 정액 구독이었는지 로그는 모릅니다. 그래서 “이 토큰이 공개 API 요율이었다면 얼마였을까”에 답합니다. 세션·프로젝트·에이전트를 서로 비교하거나 구독이 본전을 뽑는지 판단할 때 맞는 질문이고, 실제로 청구된 금액은 아닙니다.

“활동 시간”은 벽시계 시간에서 유휴를 뺀 값입니다. 사흘 뒤에 다시 이어붙인 세션은 429시간에 걸쳐 있지만 실제 작업은 3시간쯤입니다. 임계값 5분은 재서 정했습니다 — 5분과 15분 사이에서 총합이 거의 움직이지 않아, 짧은 공백과 진짜 유휴가 그 지점에서 깨끗하게 갈립니다.

요율은 모델별이며 캐시 배수를 포함합니다 (5분 캐시 쓰기 1.25×, 1시간 2×, 읽기 0.1×). 프롬프트 캐싱이 실제로 얼마를 아꼈는지가 숫자에 반영됩니다.

실행

git clone https://github.com/PYSoYa/agent-trace-viewer.git
cd agent-trace-viewer
pnpm install && pnpm dev

http://localhost:3000. 로그를 자동으로 찾아 첫 로드에 색인합니다. 설정할 것이 없습니다. Node 22.5 이상이면 내장 node:sqlite를 쓰므로 네이티브 모듈 컴파일도 없습니다.

Docker로도 실행할 수 있습니다. 로그는 읽기 전용으로 마운트하고, ~/.codex는 통째로 마운트하지 않습니다 — 그 안에 auth.json이 있고, 트레이스를 읽자고 컨테이너에 자격증명을 넘길 이유는 없습니다.