AI 코딩 도구의 실제 비용을 추적하는 방법 — 무료 로컬 대시보드 (Docker 및 클라우드 불필요)

AI 코딩 CLI (Claude Code, Codex, Gemini CLI 및 기타 도구들)는 토큰을 빠르게 소모하며, 실제 소비량을 추적하기는 쉽지 않습니다. 정액제 구독은 이를 숨기고, 도구마다 데이터가 제각각이며, IDE 어시스턴트는 벤더의 결제 페이지에만 보고하기 때문입니다. 이것은 여러분이 도구별, 모델별, 일별, 프로젝트별로 얼마를 쓰고 있는지 하나의 프라이빗한 뷰로 제공하는 작고 무료이며 완전히 로컬로 작동하는 설정입니다. 또한 비용을 절감할 수 있는 몇 가지 워크플로 습관도 함께 제공합니다.

이곳의 모든 기능은 사용자의 기기에서 실행되며 아무것도 업로드하지 않습니다. API 키, 클라우드 계정, Docker가 필요 없습니다. 이 gist에는 두 개의 작은 스크립트가 포함되어 있습니다. 예시는 Windows/PowerShell 기준이며, 아이디어는 macOS/Linux로 직접 이식 가능합니다 ( ~/.claude 경로를 변경하고 셸 스크립트를 사용하세요).

먼저 사고방식의 전환이 필요합니다: 구독(예: 월정액 요금제)의 경우, 아래의 달러 수치는 API 환산 가치(해당 토큰이 종량제 API 가격일 때의 비용)를 의미하며, 실제로 지불하는 금액이 아닙니다. 이것은 사용량 측정기이지, 여러분의 청구서가 아닙니다.

1. 즉각적인 보기: ccusage (설정 불필요) ccusage는 코딩 CLI가 이미 작성하고 있는 로컬 JSONL 로그 (~/.claude, ~/.codex, ~/.gemini, …)를 읽어 비용과 토큰을 보고합니다. 설치가 필요 없으며 npx로 실행할 수 있습니다:

npx ccusage@latest daily # 일별 비용 및 토큰
npx ccusage@latest monthly # 월별, 도구 및 모델별 분류
npx ccusage@latest session # 코딩 세션별
npx ccusage@latest blocks --live # 실시간 자동 새로고침 터미널 대시보드

blocks --live 단독으로도

Opus 4.x | 세션당 $X.XX / 오늘 $Y.YY | 시간당 $Z/hr | 컨텍스트 (ctx) 210K (40%)
(ccusage를 전역으로 설치하세요 — npm i -g ccusage — 그래야 상태 표시줄이 빠르게 작동합니다.)

1. 턴당 비용 푸터 (Claude Code Stop hook) 어시스턴트의 매 턴이 끝난 후 한 줄의 비용/컨텍스트 요약을 출력하고 싶다면, 작은 스크립트를 실행하는 Stop hook을 추가하세요. ~/.claude/settings.json 파일에 다음과 같이 작성합니다:

{
"hooks": {
"Stop": [
{ "hooks": [ { "type": "command",
"command": "powershell -NoProfile -ExecutionPolicy Bypass -File "%USERPROFILE%.claude\scripts\usage-report.ps1"" } ] }
]
}
}

스크립트(이 gist에 있는 usage-report.ps1)는 표준 입력(stdin)을 통해 hook의 JSON을 읽고, 세션 트랜스크립트(메시지 ID로 중복 제거, 모델별 가격 책정)를 집계하여 {"systemMessage": "..."} 라인을 출력합니다. 의도적으로 ASCII 전용으로 제작되었습니다. PowerShell 5.1은 표준 출력(stdout)에서 이모지를 깨뜨리며, 이 경우 호스트 프로그램에서 글자가 깨져 보일 수 있기 때문입니다.

2. 메인 빌드: 전역 및 프로젝트별 HTML 대시보드 usage-dashboard.ps1 (이 gist에 있음)은 더블 클릭으로 열 수 있는 단일 독립형 파일인 ~/.claude/usage-dashboard.html을 생성합니다. 이 대시보드는 두 가지 데이터 소스를 결합합니다:

• 도구 간 총합 / 제공자별 / 모델별 / 일일 추세 — ccusage로부터 가져옵니다 (따라서 ccusage가 감지하는 모든 CLI, 즉 Claude, Codex, Gemini CLI, 로컬 모델 등을 모두 포함합니다).
• 상세 분석이 가능한 프로젝트별 내역 — ~/.claude/projects/를 직접 스캔하여 생성합니다 (Claude Code는 프로젝트별 트랜스크립트를 로컬에 기록하는 도구입니다). 프로젝트를 클릭하면 모델별, 일별, 세션별 분포를 확장하여 볼 수 있습니다.

실행 방법:

powershell -NoProfile -ExecutionPolicy Bypass -File "$env:USERPROFILE.claude\scripts\usage-dashboard.ps1" -Open

따라 할 만한 몇 가지 설계 선택 사항:

보안 (Security): Chart.js는 CDN 대신 로컬에 포함(HTML 옆에 한 번 다운로드)됩니다. 즉, 조회 시점에 제3자 스크립트가 실행되지 않으며, 오프라인에서도 작동하고, 하위 리소스 무결성 (Subresource-Integrity) 걱정도 없습니다. 모든 동적 문자열은 innerHTML에 삽입되기 전에 HTML 이스케이프 (HTML-escaped) 처리됩니다.<br> 키(Key)도, 업로드도 없습니다: 오직 사용자의 로컬 파일만 읽습니다.<br> 일관된 합계: 프로젝트별 추정치는 단순한 가격표를 사용하므로, 그 절대 수치는 ccusage의 수치와 차이가 날 수 있습니다. 스크립트는 프로젝트별 비용을 ccusage의 권위 있는 총계에 맞춰 정규화(Normalize)합니다. 따라서 비율은 정확하게 유지되며, 단일 프로젝트가 총계를 초과할 수 없습니다. 프로젝트별 수치는 상대적인 값으로 취급하십시오. 1센트 단위까지 정확한 총계를 확인하려면 ccusage의 월간 데이터를 사용하세요.<br> 노이즈 필터링: 합성(Synthetic) 또는 과금되지 않는 트랜스크립트(Transcript) 항목은 제외됩니다.</p> <ol> <li>로컬 도구가 볼 수 없는 것 (솔직하게 말하자면): 두 개의 레이어가 있으며, 오직 하나만이 로컬에 있습니다:</li> </ol> <p>레이어 | 예시 | 로컬 및 무료인가?<br> 사용량 (토큰, 비용 환산값, 모델, 프로젝트, 시간) | CLI 도구 → 로컬 JSONL → ccusage | ✅ 예<br> 플랜 제한 및 IDE 어시스턴트 사용량 (속도 제한 윈도우, 월간 한도, 초기화 날짜; VSCode Copilot, IDE 내장 어시스턴트) | 제공업체의 계정/결제 페이지 | ❌ 로컬 소스 없음<br> IDE 어시스턴트와 플랜 제한 수치는 로컬 로그가 아닌 제공업체의 계정에 존재합니다. 따라서 로컬 대시보드는 해당 제공업체의 API를 토큰과 함께 연결하지 않는 한, 수치를 가져오는 대신 해당 페이지(예: GitHub Copilot 사용 페이지)로 딥링크(Deep-link)를 연결할 수만 있습니다. 모든 도구를 아우르는 단일 클라우드 창을 약속하는 서비스는 사용자의 로그나 키 업로드를 요구할 것입니다. 이것이 고려해야 할 트레이드오프 (Trade-off)입니다.</p> <ol> <li>보너스: 비용을 절감하는 세 가지 습관. 가장 저렴한 토큰은 두 번 쓰지 않는 토큰입니다:</li> </ol> <p>"완료 = 작성된 것이 아니라 증명된 것." 증거물(Evidence artifact) — 테스트 실행, HTTP/CLI 응답, 또는 앱이 실제로 작동하는 스크린샷 — 없이 "완료"를 받아들이지 마세요. 낭비되는 비용의 대부분은 완료되었다고 보고되었으나 실제로는 완료되지 않은 작업을 다시 수행하는 데서 발생합니다.<br> 다시 조사하지 말고, 인계하십시오 (Hand off, don't re-research).

세션을 종료할 때는 다음 단계(Next) / 미결 질문(open-questions) / 주의사항(gotchas)을 날짜가 포함된 노트에 적어두고, 다음 세션을 시작할 때 이를 읽는 것으로 시작하세요. 어제의 컨텍스트(Context)를 다시 찾아내는 것은 순전한 토큰 낭비(Token burn)입니다.<br> 범위는 위임하고, 노력의 규모를 적절히 조절하세요. 광범위한 검색은 결론을 반환하는 서브 에이전트(Sub-agents)에게 맡기고(단순한 파일 덤프의 나열이 아닌), 기계적인 편집 작업에 최대 추론 노력(Maximum reasoning effort)을 쏟지 마세요.<br> 스크립트 가져오기<br> 이 Gist에는 다음이 포함되어 있습니다:</p> <p>usage-dashboard.ps1 — 프로젝트별 글로벌 대시보드 생성기.<br> usage-report.ps1 — 턴(Turn)별 Stop-hook 푸터(Footer).<br> 이 파일들을 ~/.claude/scripts/ 폴더에 넣고, 위에서 언급한 두 개의 settings.json 스니펫(Snippet)을 연결한 뒤 대시보드 생성기를 실행하세요. 작성된 코드는 Windows/PowerShell 기준이며, macOS/Linux의 경우 ~/.claude 경로를 수정하여 사용하세요.</p> <p>면책 조항: 본 자료는 있는 그대로 제공되며, 어떠한 보증도 하지 않습니다. 모델 가격은 변동될 수 있으므로 스크립트 내의 가격 테이블을 업데이트하십시오. 달러 수치는 API 비용에 상응하는 추정치이며, 실제 청구서(Billing statements)가 아닙니다.</p> <p><a href="https://gist.github.com/Kaidanov/d1b5d63bff857c4ca551a0328f39d6ae">https://gist.github.com/Kaidanov/d1b5d63bff857c4ca551a0328f39d6ae</a></p>