CodeBurn 소개
CodeBurn은 AI 코딩 도구가 이미 디스크에 기록해 둔 세션 파일을 읽어, 토큰 사용량과 비용을 작업 유형·모델·도구·프로젝트 단위로 나눠 보여 주는 로컬 도구입니다. 청구서는 이번 달 총액이 얼마인지는 알려 주지만, 그 금액의 절반이 코드 작성이 아니라 대화에 들어갔다는 사실이나, 값싼 모델로 한 번에 끝났을 작업에 비싼 모델이 예산을 썼다는 사실은 알려 주지 않습니다. CodeBurn은 그 분해를 대신합니다.
동작 방식의 핵심은 아무것도 중간에 끼우지 않는다는 점입니다. 프록시나 래퍼를 두지 않고 API 키도 요구하지 않으며, 각 도구가 남긴 세션 로그를 읽기 전용으로 파싱합니다. 가격 정보는 LiteLLM의 모델 가격 데이터에서 받아와 로컬에 하루 동안 캐시하고, Claude와 GPT-5 계열 모델에는 하드코딩된 예비 가격표를 둬서 이름이 흐릿하게 일치할 때 잘못된 단가가 적용되는 것을 막습니다. 실행 결과는 어디로도 전송되지 않습니다.
CodeBurn은 스스로를 36종의 AI 코딩 도구와 에이전트를 다루는 무료 오픈소스 도구로 소개하고 있으며, Claude Code, Cursor, Codex, Gemini CLI, Grok 등이 지원 목록에 들어 있습니다. 본 게시물에서는 CodeBurn이 제공하는 네 가지 화면, 도구별 세션 데이터를 읽는 방식, 낭비 패턴을 찾아 고쳐 주는 optimize 명령, 모델 비교와 커밋 연계 분석, 그리고 에이전트에 붙여 쓰는 MCP 서버를 정리합니다.
CodeBurn의 네 가지 화면
CodeBurn은 같은 집계 결과를 네 가지 화면으로 보여 줍니다. 터미널 대시보드는 npx codeburn으로 설치 없이 바로 열리고 기본값은 최근 7일이며, 화살표 키로 기간을 바꾸고 q로 종료합니다. 상단에는 비용·토큰·호출 수·캐시 적중률 합계가, 아래에는 일별 비용 차트와 프로젝트·모델·작업 유형별 분해가 놓입니다.
codeburn web은 같은 분해를 차트로 그리는 로컬 웹 대시보드를 http://localhost:4747에 띄웁니다. 사용량 그래프는 선택한 기간에 따라 15분·1시간·일 단위로 묶이고, 세션별 선과 모델별 선을 전환할 수 있습니다. 서버는 로컬호스트에만 바인딩되며 데이터는 디스크에서 읽습니다.
macOS에서는 codeburn menubar가 최신 앱을 받아 ~/Applications에 설치하고 실행합니다. 메뉴바 아이콘에는 설정에서 고른 기간의 지출액이 표시되고(기본값은 오늘), 클릭하면 기간 전환·추세·예측·모델 분해·낭비 진단 결과·CSV와 JSON 내보내기가 담긴 팝오버가 열립니다. 30초마다 갱신되며, 배터리나 저전력 모드에서는 갱신 간격을 자동으로 늘립니다. Linux에서는 GNOME 45 이상용 셸 확장이 같은 역할을 하고, Windows에서는 웹 대시보드가 상시 화면 역할을 합니다.
네 번째 화면인 데스크톱 앱은 macOS(Apple Silicon과 Intel), Windows(Microsoft Store), Linux(deb, rpm, AppImage) 빌드가 릴리스로 배포됩니다. 실행 요건은 Node.js 22.13 이상과 디스크에 세션 데이터가 있는 지원 도구 하나이며, Cursor와 OpenCode를 읽을 때 필요한 better-sqlite3는 자동으로 설치됩니다.
CodeBurn이 세션 데이터를 읽는 방식
CodeBurn의 CLI는 Node.js로 작성되어 있고, macOS 메뉴바 앱(Swift)과 GNOME 확장(JavaScript)은 CLI를 실행해 그 JSON 출력만 소비하는 구조입니다. 저장소의 docs/architecture.md에 실린 구조도가 이 관계를 그대로 보여 줍니다.
+----------------------+ +-----------------+
| mac/ (Swift) | ---> | |
+----------------------+ | src/cli.ts |
| gnome/ (JavaScript) | ---> | (the CLI) |
+----------------------+ | |
| status |
| --format |
| menubar-json |
+-----------------+
|
v
+----------------------------+
| session files on disk |
| (JSONL, SQLite, protobuf) |
+----------------------------+
읽는 위치와 형식은 도구마다 다릅니다. Claude Code는 ~/.claude/projects/<경로>/<세션 ID>.jsonl의 각 어시스턴트 항목에서 모델 이름과 입력·출력·캐시 읽기·캐시 쓰기 토큰, 도구 호출 블록을 가져옵니다. Codex는 ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl의 token_count 이벤트를 읽고 작업 디렉토리를 기준으로 프로젝트를 붙입니다. Cursor는 globalStorage의 SQLite 파일을 읽는데, 출력 토큰이 답변 길이 기반 추정값이고 캐시 토큰은 서버 쪽에만 있어서 긴 대화에서는 실제보다 적게 집계된다는 점을 CodeBurn이 함께 밝히고 있습니다.
중복 집계를 막는 방식도 도구별로 다릅니다. Claude는 API 메시지 ID로, Codex는 누적 토큰 교차 검증으로, Cursor는 대화와 타임스탬프로, Gemini CLI는 세션 ID로 중복을 제거합니다. 어떤 도구가 0으로 나오거나 값이 이상해 보일 때는 codeburn doctor가 탐색한 디렉토리와 발견한 세션 수, 파싱 성공 비율, 한 줄 판정을 보여 줍니다. 이 명령은 완전히 오프라인·읽기 전용으로 동작하며 캐시나 설정을 쓰지 않습니다.
작업 유형 분류는 13개 범주로 이루어지고, 도구 사용 패턴과 사용자 메시지의 키워드만으로 판정합니다. 별도의 LLM 호출 없이 결정적으로 동작합니다. Edit·Write 도구가 쓰이면 Coding, Read·Grep·WebSearch만 쓰이고 편집이 없으면 Exploration, 도구가 전혀 없는 순수 텍스트 교환이면 Conversation으로 분류되는 식입니다.
CodeBurn의 낭비 진단과 자동 수정
codeburn optimize는 최근 30일 세션과 ~/.claude/ 설정을 훑어 낭비 패턴을 찾습니다. 여러 세션에서 같은 내용을 반복해 읽는 파일, 읽기 대비 편집 비율이 낮아 재시도가 늘어나는 패턴, 상한이 없는 BASH_MAX_OUTPUT_LENGTH 때문에 버려지는 셸 출력, 쓰지 않는데도 매 세션 도구 스키마 비용을 물리는 MCP 서버, 정의만 되어 있고 한 번도 호출되지 않은 에이전트·스킬·슬래시 명령, @-임포트 확장까지 계산한 비대한 CLAUDE.md가 검출 대상입니다.
각 항목에는 예상 절감 토큰과 금액, 그리고 그대로 붙여 넣을 수 있는 수정안이 따라옵니다. CLAUDE.md에 넣을 한 줄, 설정할 환경 변수, 쓰지 않는 항목을 보관 디렉토리로 옮기는 mv 명령 중 하나입니다. 항목은 영향도와 관측된 낭비량을 함께 반영한 긴급도 순으로 정렬되고, 전체는 A부터 F까지의 설정 건강 등급으로 묶입니다. 다시 실행하면 48시간 최근 창을 기준으로 각 항목이 신규·개선·해결 중 어디에 해당하는지 분류됩니다.
설정 계열 항목은 codeburn optimize --apply로 바로 적용할 수 있습니다. 모든 변경은 적용 전에 백업과 저널에 기록되므로 codeburn act list로 이력을 보고 codeburn act undo <id>로 원래 파일을 되돌릴 수 있습니다. 적용 이후 파일이 바뀌었다면 --force 없이는 되돌리기를 거부합니다. 적용한 수정이 3일 이상 지나면 codeburn act report가 예상 절감액과 실제 세션이 보인 결과를 비교하고, 이후의 optimize 실행 헤더에 그 실측치가 표시됩니다.
예산 자체를 막는 쪽은 codeburn guard입니다. Claude Code의 settings.json에 훅을 설치해 세션 비용을 지켜보다가, 기본값 5달러의 소프트 캡을 넘으면 세션 중 한 번 경고하고, 15달러의 하드 캡에서는 세션을 중단합니다(codeburn guard allow로 해당 세션만 해제). 3달러의 체크포인트를 넘긴 세션이 편집도 커밋도 없이 끝나면 이름 있는 산출물을 정해 새로 시작하라고 권합니다. 훅은 실패 시 열린 상태로 동작하므로, 훅이 깨져도 세션을 막지 않습니다.
CodeBurn의 모델 비교와 성과 추적
codeburn compare는 같은 사람이 실제로 한 작업에서 어떤 모델이 나았는지를 두 축으로 비교합니다. 성능 축에는 재시도 없이 성공한 편집의 비율인 원샷 성공률, 편집 턴당 평균 재시도 횟수, 모델이 자기 실수를 스스로 고친 턴의 비율이 들어갑니다. 효율 축에는 호출당 비용, 편집 턴당 비용, 호출당 출력 토큰, 입력 중 캐시에서 온 비율이 들어갑니다.
원샷 성공률의 정의는 파일 단위입니다. 같은 파일을 셸 명령 사이에 두고 다시 편집하면 재시도로 세고, 셸 단계 사이에 서로 다른 파일을 편집하면 재시도로 세지 않습니다. 파일 단위 추적은 Claude와 Codex, Goose에서 동작하고 다른 도구는 도구 이름 기반 판정으로 대체됩니다.
codeburn yield는 지출이 실제로 배포까지 갔는지를 git 커밋과 대조합니다. 세션은 커밋이 main에 들어간 Productive, 나중에 되돌려진 Reverted, 커밋이 없거나 병합되지 않은 Abandoned, 다른 세션과 병행 실행돼 커밋이 더 좁은 창으로 귀속된 Ambiguous로 분류됩니다. 귀속 방식은 타임스탬프 창 기반 추정입니다. 각 커밋은 그것을 포함하는 가장 좁은 창 하나에만 배정되고, JSON 보고서에는 methodology: "timestamp-window"가 함께 실립니다.
CodeBurn을 에이전트에 붙이는 MCP 서버
codeburn mcp는 stdio 기반 로컬 MCP 서버로 동작해, 대화 도중에 "이번 주 토큰이 어디로 갔는지"를 에이전트가 직접 물어볼 수 있게 합니다. Claude Code에는 다음 한 줄로 등록합니다.
claude mcp add codeburn -- npx -y codeburn mcp
노출하는 도구는 두 개입니다. get_usage는 도구·모델·프로젝트·작업 단위 분해를 포함한 사용량과 지출을 빠르게 돌려주고, get_savings는 낭비 항목과 재시도 비용, 라우팅 낭비 같은 절감 여지를 더 깊게 분석해 돌려줍니다. 프로젝트 이름은 기본적으로 가명으로 처리되며, 에이전트가 include_project_names: true로 요청할 때만 실제 이름을 봅니다.
CodeBurn이 지원하는 도구 목록
지원 도구는 자동으로 감지되고, 디스크에 세션 데이터가 있는 도구가 여러 개면 대시보드에서 p로 전환합니다. Claude Code와 Claude Desktop, Cline, Codex, Cursor, Devin, Gemini CLI, GitHub Copilot, OpenCode, Qwen, Kimi Code CLI, Goose, Warp, Zed, Grok Build 등이 목록에 있고, 각 도구의 정확한 데이터 위치와 저장 형식, 알려진 특이사항은 저장소의 docs/providers/ 아래 문서에 도구별로 정리되어 있습니다. --provider 플래그로 모든 명령을 한 도구로 좁힐 수 있고, 새 도구를 추가하는 작업은 파일 하나를 더하는 일이라고 밝히고 있습니다.
표시 통화는 codeburn currency 명령으로 바꿉니다. ISO 4217 통화 코드 162종을 지원하며 환율은 유럽중앙은행 데이터를 쓰는 Frankfurter에서 받아 24시간 캐시합니다. 설정한 통화는 대시보드와 메뉴바, CSV·JSON 내보내기에 모두 적용됩니다.
CodeBurn의 라이선스
CodeBurn은 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.
CodeBurn 공식 홈페이지
CodeBurn 프로젝트 GitHub 저장소
더 읽어보기
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다! 텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다. 
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 