CodeBurn 튜토리얼 – AI 코딩 에이전트 토큰 사용량 한눈에 파악하기

설치
Step 1: 대시보드 실행
Step 2: 어디에 토큰을 쓰고 있는지 파악
Step 3: 프로바이더별 비교
Step 4: 빠른 현황 파악 (상태바 모드)
Step 5: 정기 자동 갱신 (macOS)
Step 6: 데이터 내보내기
통화 설정
활용 팁
관련 문서

Claude Code, Codex, Cursor를 쓰다 보면 자연스럽게 드는 궁금증이 생긴다. “이번 달에 얼마나 썼지?”, “어떤 작업에 토큰을 가장 많이 쓰고 있지?”, “이 프로젝트에서 실제로 비용 대비 효율이 좋은가?” codeburn을 사용하면 API 키나 래퍼 없이, 디스크에 저장된 세션 데이터를 직접 읽어 이 질문들에 즉시 답할 수 있다.

설치

npm install -g codeburn

또는 설치 없이 바로 실행:

npx codeburn

Node.js 20 이상이 필요하다.

Step 1: 대시보드 실행

codeburn

처음 실행하면 자동으로 디스크에서 세션 데이터를 탐색한다. Claude Code를 쓰고 있다면 ~/.claude/projects/를 읽는다. 별도 설정이 필요 없다.

TUI가 열리면 상단에 오늘/7일/30일/월별 비용 차트, 아래에 세부 분석이 표시된다. ←→ 화살표로 기간을 전환한다.

Step 2: 어디에 토큰을 쓰고 있는지 파악

CodeBurn은 도구 사용 패턴과 키워드를 기반으로 13개 태스크 카테고리로 자동 분류한다. “AI가 어디에서 가장 많이 고생하는가”를 한눈에 볼 수 있다.

주목할 컬럼:

Cost — 카테고리별 누적 비용
1-shot % — 첫 번째 시도에 성공한 비율. 낮으면 해당 작업에서 AI가 반복 수정을 많이 하고 있다는 뜻

예시: Coding 1-shot이 60%라면, Edit→Bash→Edit 재시도 사이클이 잦다는 신호다. 프롬프트 전략이나 컨텍스트 제공 방식을 개선할 여지가 있다.

Step 3: 프로바이더별 비교

여러 AI 도구를 병행 사용 중이라면 프로바이더별로 비교할 수 있다.

codeburn report --provider claude  # Claude Code만
codeburn report --provider cursor  # Cursor만
codeburn report                    # 전체 합산

Step 4: 빠른 현황 파악 (상태바 모드)

터미널에서 한 줄로 현황을 확인하려면:

codeburn status            # 오늘 + 이번 달 요약
codeburn status --format json  # JSON 출력 (스크립트 연동용)

Step 5: 정기 자동 갱신 (macOS)

macOS를 사용 중이라면 SwiftBar를 설치한 뒤 메뉴바 위젯을 추가할 수 있다.

brew install --cask swiftbar
codeburn install-menubar

이후 5분마다 오늘 누적 비용이 메뉴바에 표시된다.

Step 6: 데이터 내보내기

팀 보고나 스프레드시트 분석이 필요하면:

codeburn export            # CSV (오늘, 7일, 30일)
codeburn export -f json    # JSON
codeburn export --provider claude  # Claude만 내보내기

통화 설정

한국 원화(KRW)로 보고 싶다면:

codeburn currency KRW

유럽중앙은행 환율 기준으로 24시간 캐시해 사용한다.

활용 팁

1-shot 성공률이 낮은 카테고리를 찾아 해당 작업의 프롬프트 패턴을 개선한다
월별 비용 추이를 CSV로 내보내 팀 AI 도입 ROI 리포트에 활용한다
codeburn report --refresh 60으로 60초마다 자동 갱신되는 실시간 모니터를 띄울 수 있다

AI Sparkup