CodeBurn 사용법: AI 코딩 토큰 비용을 로컬에서 추적하는 실전 가이드

Claude Code, Codex, Cursor 같은 AI 코딩 도구를 여러 개 쓰다 보면 월말 총액은 보여도 어느 프로젝트와 작업에서 토큰이 많이 쓰였는지는 파악하기 어렵습니다. refer/0814 자료에 소개된 CodeBurn 공식 저장소는 이 문제를 로컬 세션 기록 분석으로 풀어낸 MIT 라이선스 오픈소스 도구입니다.

다만 참고 이미지의 정보는 이미 빠르게 바뀌었습니다. 2026년 8월 14일 공식 저장소의 main 브랜치 기준으로 CodeBurn은 버전 0.9.20이며, README는 Claude Code·Codex·Cursor를 포함한 40개 AI 도구와 에이전트를 지원한다고 설명합니다. 이 글은 오래된 스타 수나 초기 지원 목록 대신 현재 공식 문서와 패키지 설정을 기준으로 실제 적용 가능한 범위를 정리합니다.

초보자를 위한 핵심 용어 사전
CodeBurn은 무엇을 하는 도구인가
실제로 적용 가능한 범위
3분 설치와 첫 실행
업무에 적용하는 다섯 가지 사용법
적용하면 어떤 효과를 기대할 수 있나
어떤 사용자와 목적에 적합한가
정확도와 개인정보 보호에서 알아둘 한계
추천 도입 순서와 결론

초보자를 위한 핵심 용어 사전

토큰(Token): AI가 문장을 읽고 생성할 때 사용하는 계산 단위입니다. 글자 수와 정확히 같지는 않으며 입력, 출력, 캐시 읽기와 쓰기 등에 각각 비용이 붙을 수 있습니다.
세션(Session): 사용자가 AI 코딩 도구와 작업한 한 묶음의 대화와 도구 실행 기록입니다.
캐시(Cache): 반복되는 입력을 다시 계산하지 않고 재사용하는 기능입니다. 캐시 적중률이 높으면 같은 맥락을 반복해서 처리하는 비용을 줄일 가능성이 커집니다.
TUI: Terminal User Interface의 약자로, 터미널 안에서 키보드로 조작하는 화면형 프로그램입니다.
관측 가능성(Observability): 총비용만 보는 데서 그치지 않고 어떤 모델, 프로젝트, 작업, 도구가 비용을 만들었는지 추적할 수 있는 상태입니다.
MCP: Model Context Protocol의 약자로, AI 클라이언트가 외부 도구의 기능을 표준 방식으로 호출하게 해주는 연결 규격입니다.
원샷 성공률(One-shot rate): 파일을 수정한 뒤 다시 고치는 반복이 없었던 비율을 나타내는 CodeBurn의 지표입니다. 결과물의 품질을 직접 보증하는 점수는 아닙니다.

CodeBurn은 무엇을 하는 도구인가

CodeBurn은 AI 모델 호출을 대신 처리하는 프록시가 아닙니다. 이미 Claude Code, Codex, Cursor 같은 도구가 컴퓨터에 남긴 세션 파일이나 로컬 데이터베이스를 읽고 다음과 같이 다시 분류합니다.

날짜별 토큰과 추정 비용
프로젝트별·모델별 비용
코딩, 디버깅, 탐색, 계획, 테스트 등 작업 유형별 사용량
파일 읽기·수정, 셸 명령, MCP 서버별 사용 패턴
수정 후 재수정이 발생한 흐름과 원샷 성공률
캐시 적중률과 반복해서 읽은 파일

로컬 세션 기록을 프로젝트·모델·작업 유형별로 분석하는 흐름

분류 과정에는 별도의 LLM 호출을 사용하지 않습니다. 공식 문서에 따르면 사용자 메시지의 키워드와 도구 사용 패턴을 이용한 결정적 규칙으로 13개 작업 범주를 나눕니다. 따라서 분류 비용이 추가되지 않고 같은 기록은 같은 규칙으로 분석되지만, 사람이 의도한 업무 의미와 항상 일치한다고 볼 수는 없습니다.

실제로 적용 가능한 범위

정확한 토큰 기록이 남는 개인 개발 환경

Claude Code는 ~/.claude/projects/ 아래 JSONL 기록을, Codex는 ~/.codex/sessions/와 보관된 세션을 읽습니다. 이들 기록에 모델명과 입력·출력·캐시 토큰 정보가 있으면 모델과 프로젝트별 비용을 비교적 세밀하게 계산할 수 있습니다.

Gemini CLI, OpenCode, GitHub Copilot, Kiro, Antigravity, Warp 등도 공식 지원 목록에 포함됩니다. 다만 제공자마다 저장 형식과 기록하는 항목이 다르므로 지원 여부와 정확도는 같은 뜻이 아닙니다. 현재 지원 목록과 세부 경로는 공식 README의 Supported tools에서 확인하는 것이 가장 안전합니다.

Cursor처럼 일부 값이 추정되는 환경

Cursor는 운영체제별 state.vscdb 데이터베이스를 읽습니다. 공식 문서에 따르면 입력 토큰은 Cursor의 대화별 컨텍스트 정보를 사용하지만 출력 토큰은 응답 텍스트 길이를 바탕으로 추정하며, 서버 측 캐시 토큰은 확인할 수 없습니다. 긴 대화에서는 Cursor 관리자 화면보다 적게 집계될 수 있으므로 회계용 확정 금액보다 추세 비교용으로 보는 편이 맞습니다.

개인용에서 소규모 팀까지

한 컴퓨터에서는 TUI와 로컬 웹 대시보드를 사용할 수 있습니다. 같은 로컬 네트워크의 여러 기기는 PIN으로 페어링해 합산할 수 있고, 팀 원격 측정용 sync 기능도 프리뷰로 제공됩니다. 그러나 중앙 결제 시스템, 조직별 권한 관리, 감사 로그가 필요한 대기업 FinOps 플랫폼을 완전히 대체하는 용도는 아닙니다.

지원 운영체제와 화면

Windows: 터미널 대시보드와 codeburn web 로컬 웹 화면
macOS: 터미널, 웹 화면, 네이티브 메뉴 막대 앱
Linux: 터미널과 웹 화면, GNOME 45 이상용 패널 확장

3분 설치와 첫 실행

현재 package.json은 Node.js 22.13 이상을 요구합니다. 먼저 터미널 또는 PowerShell에서 버전을 확인합니다.

node --version

설치 없이 바로 실행하려면 다음 한 줄이면 됩니다.

npx codeburn

자주 사용할 계획이라면 전역으로 설치합니다.

npm install -g codeburn
codeburn

첫 화면은 최근 7일을 기준으로 열립니다. 여러 AI 도구의 세션이 발견되면 p 키로 제공자를 바꿀 수 있고 q 키로 종료합니다. 데이터가 나타나지 않거나 일부 도구만 잡힐 때는 진단 명령으로 탐색 경로와 파싱 상태부터 확인합니다.

codeburn doctor
codeburn doctor --provider codex

브라우저 차트가 편하면 로컬 전용 웹 화면을 엽니다.

codeburn web

기본 주소는 http://localhost:4747입니다. 다른 기기에 공개하는 호스팅 서비스가 아니라 현재 컴퓨터의 로컬 서버에 연결하는 방식입니다.

업무에 적용하는 다섯 가지 사용법

1. 오늘과 이번 달의 소비 확인

codeburn today
codeburn month
codeburn status

일일 급증을 빠르게 찾거나 월간 사용량이 평소 흐름을 벗어났는지 확인할 때 적합합니다.

2. 프로젝트와 기간을 나눠 비교

codeburn report -p 30days
codeburn report --from 2026-08-01 --to 2026-08-14
codeburn report --provider codex

기능 개발, 유지보수, 실험 프로젝트 중 어디에서 비용이 커졌는지 비교할 수 있습니다. 여러 제공자를 함께 쓰는 사용자는 동일 기간을 제공자별로 나눠 보는 것이 좋습니다.

3. 낭비 후보 찾기

codeburn optimize
codeburn optimize -p week
codeburn optimize --provider claude

반복해서 읽는 파일, 과도한 셸 출력, 사용하지 않는 MCP 서버, 비대한 지침 파일, 재수정 루프 등을 찾아 예상 비용과 조치 후보를 보여줍니다. 자동 수정 전에는 반드시 계획만 확인합니다.

codeburn optimize --apply --dry-run

--apply는 설정이나 에이전트 파일을 실제로 바꿀 수 있는 기능입니다. CodeBurn은 변경 전 백업과 기록을 남기고 codeburn act undo를 제공하지만, 팀 설정 파일이라면 저장소 정책과 리뷰 절차를 먼저 확인해야 합니다.

4. CSV와 JSON으로 회고 자료 만들기

codeburn export
codeburn export -f json
codeburn report --format json

주간 회고, 프로젝트 원가 추정, 모델 교체 전후 비교에 활용할 수 있습니다. JSON 출력은 자동화 파이프라인에서 프로젝트별 비용이나 캐시 적중률만 골라낼 때 유용합니다.

5. AI 에이전트가 사용량을 직접 조회하게 연결

Claude Code에서는 공식 예시처럼 로컬 MCP 서버를 추가할 수 있습니다.

claude mcp add codeburn -- npx -y codeburn mcp

연결 후 에이전트는 get_usage와 get_savings 도구로 사용량과 절감 후보를 조회할 수 있습니다. 프로젝트명은 기본적으로 가명 처리되지만, MCP 클라이언트가 받아가는 분석 결과의 범위는 조직의 보안 정책에 맞춰 확인해야 합니다.

적용하면 어떤 효과를 기대할 수 있나

비용 문제를 총액이 아닌 원인으로 바꾼다

“이번 달 AI 비용이 비싸다”는 말만으로는 행동을 정하기 어렵습니다. CodeBurn을 적용하면 특정 프로젝트, 고가 모델, 반복 수정, 불필요한 파일 읽기처럼 조치 가능한 원인으로 나눠 볼 수 있습니다.

모델 선택을 감이 아닌 기록으로 검토한다

간단한 작업에 고가 모델이 집중됐는지, 저렴한 모델로 바꾼 뒤 재시도가 늘었는지를 비용과 원샷 성공률로 함께 비교할 수 있습니다. 단순히 가장 싼 모델을 고르는 대신 완료 가능성과 재작업 비용을 같이 판단하게 해줍니다.

프롬프트와 프로젝트 설정을 개선할 단서를 얻는다

캐시 적중률이 장기간 낮거나 같은 파일을 여러 세션에서 계속 읽는다면 시스템 지침과 컨텍스트 구성이 안정적이지 않을 수 있습니다. 사용하지 않는 MCP 서버가 매 세션 도구 스키마를 차지하는지도 확인할 수 있습니다.

팀 회고를 재현 가능한 데이터로 바꾼다

기간과 제공자를 고정해 JSON이나 CSV로 내보내면 “이번 스프린트에서 어떤 작업이 AI 비용을 만들었는가”를 같은 기준으로 반복 비교할 수 있습니다. 다만 저장된 세션만 집계하므로 삭제됐거나 다른 기기에 남은 기록은 자동으로 복구되지 않습니다.

어떤 사용자와 목적에 적합한가

사용자	적합한 목적	추천 기능
Claude Code·Codex를 매일 쓰는 개인 개발자	프로젝트별 비용과 재시도 확인	`today`, `report`, `optimize`
Cursor와 CLI 에이전트를 함께 쓰는 사용자	도구별 사용 추세 비교	`--provider`, `web`
여러 모델을 실험하는 AI 엔지니어	모델별 비용·캐시·성공 흐름 비교	`compare`, JSON 출력
소규모 개발팀 리드	주간 회고와 예산 이상 징후 파악	`overview`, `export`, 기기 페어링
보안상 원본 대화를 외부 분석 서비스에 올리기 어려운 조직	로컬 우선 사용량 진단	기본 TUI, 로컬 웹, `doctor`
자동화 도구를 만드는 개발자	사용량 데이터를 스크립트나 에이전트에 연결	JSON, MCP

반대로 회사 전체 청구서와 정확히 대조해야 하는 재무팀, 여러 조직의 권한과 비용 배부를 중앙에서 관리해야 하는 대기업, 세션 파일을 남기지 않는 환경에는 단독 도구로 충분하지 않습니다.

정확도와 개인정보 보호에서 알아둘 한계

표시 비용은 청구서 원본이 아니다

CodeBurn은 세션에 기록된 토큰 수에 LiteLLM 가격표를 적용합니다. 가격 정보는 로컬에 24시간 캐시되고, 알려진 Claude와 GPT-5 모델에는 오매칭을 막는 폴백이 있습니다. 그래도 구독제 포함량, 크레딧, 조직 할인, 공급자별 반올림과 비공개 캐시는 실제 청구 방식과 다를 수 있습니다.

제공자별 정확도가 다르다

Claude Code와 Codex처럼 실제 토큰 이벤트를 남기는 도구와, 응답 길이로 일부 값을 추정하는 Cursor·Kiro 같은 도구를 같은 정밀도로 해석하면 안 됩니다. codeburn audit로 제공자와 모델별 숫자의 출처를 확인한 뒤 추정값은 추세용으로 사용하세요.

codeburn audit

로컬 우선과 완전한 오프라인은 다르다

기본 분석은 로컬 세션 파일을 읽으며 프록시나 API 키가 필요 없습니다. 다만 최신 가격표를 받는 네트워크 요청, 사용자가 직접 활성화하는 로컬 네트워크 기기 공유, 원격 sync push, MCP 클라이언트 연결은 각각 통신 경계가 달라집니다.

특히 sync push는 프롬프트나 코드를 보내지 않는다고 공식 문서에 명시돼 있지만 토큰 수, 비용, 모델, 프로젝트 정보는 설정한 원격 엔드포인트로 전송합니다. 민감한 프로젝트에서는 기본 로컬 모드만 사용하고 동기화 기능을 켜기 전에 전송 항목과 수신 서버를 검토해야 합니다.

자동 최적화는 코드 품질을 판단하지 않는다

낮은 원샷 성공률은 어려운 문제를 제대로 검증한 결과일 수도 있고, 높은 원샷 성공률은 테스트가 부족했던 결과일 수도 있습니다. CodeBurn 지표는 문제를 찾는 출발점이지 성과 평가나 개발자 평가의 단독 기준이 아닙니다.