🧌 tokkaebi

Claude Code를 쓰면서 토큰을 얼마나 썼는지, 돈으로 얼마인지 보여주는 CLI 도구

tok(token) + 도깨비 — 밤새 토큰을 쓸어가는 도깨비를 내 편으로.

✨ 소개

Claude Code는 쓸 때마다 내 컴퓨터에 사용 기록을 남깁니다. tokkaebi는 그 기록을 읽어서 "오늘 얼마 썼지?", "어떤 프로젝트가 돈을 많이 먹었지?", "캐시 덕분에 얼마나 아꼈지?" 를 터미널에서 바로 보여줍니다.

• 내 컴퓨터 안에서만 동작 — 사용 데이터를 어디에도 보내지 않습니다. 서버도, 로그인도 없습니다
• 설치 전 기록까지 소급 집계 — 원본 기록을 직접 읽기 때문에, 오늘 설치해도 지난달 사용량까지 다 보입니다
• 원화 감각의 정확한 비용 — 같은 응답이 기록에 여러 번 중복으로 남는 것을 걸러내고(안 거르면 약 2.4배 뻥튀기), 캐시 종류별로 다른 단가까지 반영합니다
• 회사 환경 그대로 지원 — Anthropic 직접 계약은 물론, 회사가 AWS Bedrock·Google Vertex 경유로 Claude Code를 운용해도 모델을 알아보고 비용을 계산합니다

$ tokkaebi today
✔ 파일 269개 확인 · +16건 수집 (0.0초)

오늘 사용량 · 2026-08-11 (화) · $87.27

모델별
┌────────────────┬───────┬─────────┬────────────┬───────────┬────────┬──────────┐
│ 모델           │ 입력  │ 출력    │ 캐시 읽기  │ 캐시 쓰기 │ 비용   │          │
│ claude-fable-5 │ 2,316 │ 316,010 │ 44,645,376 │ 1,337,083 │ $86.88 │ ▮▮▮▮▮▮▮▮ │
│ claude-opus-5  │    28 │      35 │    329,533 │    36,817 │  $0.40 │ ▮▯▯▯▯▯▯▯ │
│ 합계           │ 2,344 │ 316,045 │ 44,974,909 │ 1,373,900 │ $87.27 │          │
└────────────────┴───────┴─────────┴────────────┴───────────┴────────┴──────────┘

프로젝트 · 브랜치별
┌───────────────┬───────────────────┬───────┬─────────┬────────────┬───────────┬────────┬──────────┐
│ 프로젝트      │ 브랜치            │ 입력  │ 출력    │ 캐시 읽기  │ 캐시 쓰기 │ 비용   │          │
│ tokkaebi      │ main              │   257 │ 159,844 │ 31,068,469 │   203,932 │ $43.14 │ ▮▮▮▮▮▮▮▮ │
│ guksu-trading │ fix/ops-hardening │    40 │  15,373 │  3,825,763 │   404,910 │ $12.69 │ ▮▮▯▯▯▯▯▯ │
└───────────────┴───────────────────┴───────┴─────────┴────────────┴───────────┴────────┴──────────┘

💰 캐시 절감  $390.21  — 캐시가 없었다면 오늘 $477.48
🧌 연속 사용  2일째

🎯 주요 기능

| 명령 | 보여주는 것 | | --- | --- | | tokkaebi today | 오늘 총비용 + 모델별 · 프로젝트/브랜치별 사용량, 캐시 절감액, 연속 사용일 | | tokkaebi week / month | 최근 7일 / 이번 달 — 날짜별 추이 + 프로젝트별 합계 | | tokkaebi heatmap | 요일 × 시간대 히트맵 — 내가 언제 많이 쓰는지 색 블록으로 | | tokkaebi trend | 주간 비용 추이 — 스파크라인(▁▂▅▇) + 전주 대비 증감 | | tokkaebi sessions --top 10 | 돈을 가장 많이 쓴 작업 세션 순위 (언제 · 어느 프로젝트 · 어느 브랜치) | | tokkaebi agents / skills | 서브에이전트별 / 스킬별 비용 — 보조 AI가 얼마 쓰는지 | | tokkaebi cache | 캐시 심층 분석 — 히트율, 캐시 종류별 비중, 절감액 추이 | | tokkaebi budget set 200 | 월 예산 설정 — today에 게이지가 붙고 "이 속도면 월말 $X" 예측 | | tokkaebi status | 셸 프롬프트·tmux용 한 줄 요약 (0.1초, 동기화 없음) | | tokkaebi wrapped | 월간/연간 결산 — 최다 프로젝트, 최장 스트릭, 새벽 코딩 비율, 도깨비 등급 | | tokkaebi sync | 새 기록만 골라 저장하고 결과 리포트 출력 |

• 조회 명령은 실행할 때마다 알아서 최신 기록을 반영합니다 (--no-sync로 생략 가능)
• 모든 명령에 --json이 있어서 스크립트나 다른 도구에서 데이터로 받아 쓸 수 있습니다
• 표마다 비용 비례 막대(▮▮▮▯▯)가 붙어 어디에 돈이 몰렸는지 한눈에 보입니다
• 누적 토큰이 임계값을 넘으면 등급이 오릅니다 — 아기 도깨비부터 전설의 도깨비 신까지 🧌

🛠️ 기술 스택

| 영역 | 선택 | 이유 | | --- | --- | --- | | 언어 | TypeScript (strict) | 파싱 실수·필드 오타를 컴파일 단계에서 차단 | | 저장 | SQLite (better-sqlite3) | 파일 하나로 끝나는 로컬 DB — 서버 없이 빠른 집계 | | 검증 | zod | 버전마다 조금씩 다른 기록 형식을 안전하게 받아들이고, 이상한 줄은 건너뜀 | | CLI | commander + cli-table3 + picocolors | 가벼운 조합으로 한글 도움말·표·색상 출력 | | 단가 | LiteLLM 공개 단가표 | 모델별 가격을 자동으로 받아오고(하루 1번), 오프라인이면 내장 백업 단가 사용 | | 테스트 | vitest | 모든 핵심 로직을 테스트 먼저 작성(TDD) |

🏗️ 동작 방식

~/.claude/projects/**/*.jsonl        ~/.tokkaebi/data.db
  (Claude Code가 남기는 기록)   ──►    (토큰 수·모델·시각만 저장)   ──►   터미널 표 출력
                파싱·중복 제거              집계 쿼리                 조회 시점에 단가 곱하기

• 새 기록만 읽습니다 — 파일마다 "어디까지 읽었는지"를 기억해두고, 다음 실행 때는 그 뒤에 쌓인 부분만 읽습니다. 269개 파일(135MB) 첫 수집이 1초, 이후에는 순간입니다
• 중복을 걸러냅니다 — Claude Code는 응답 하나를 여러 줄에 나눠 기록하면서 토큰 수를 줄마다 복사해 둡니다. 그대로 더하면 약 2.4배 부풀려지므로, 요청 ID 기준으로 한 번만 셉니다
• 비용은 저장하지 않고 볼 때 계산합니다 — 단가표가 바뀌어도 과거 기록의 비용이 자동으로 다시 계산됩니다
• 모르는 형식은 죽지 않고 건너뜁니다 — Claude Code가 업데이트되어 기록 형식이 바뀌어도 도구가 멈추지 않고, 건너뛴 줄 수를 sync 리포트에 보여줍니다

🔒 프라이버시 원칙

1. 대화 내용은 저장하지 않습니다 — DB에 들어가는 것은 토큰 수·모델명·시각·프로젝트 경로·브랜치명뿐입니다. 프롬프트/응답 본문은 어떤 형태로도 저장하지 않으며, 스키마 차원에서 금지하고 있습니다.
2. 밖으로 보내지 않습니다 — 네트워크 요청은 모델 단가표 다운로드 딱 하나이며, 사용 데이터는 어디로도 전송되지 않습니다. 인터넷이 없어도 전부 동작합니다.

🧪 테스트

71 tests — 파서·비용 계산·저장·집계 핵심 로직을 전부 테스트 먼저(TDD) 작성했습니다.

• 실제 기록에서 가져와 익명화한 샘플 파일 9종으로 검증: 중복 기록, 버전별 형식 차이, 쓰다 만 줄, 서브에이전트 기록, API 에러 기록 등
• 정확성 교차검증: 도구가 센 기록 수와 jq로 따로 센 수가 정확히 일치 (7,360 == 7,360)

pnpm test        # 전체 테스트
pnpm typecheck   # 타입 검사

📁 프로젝트 구조

packages/
  core/   # 엔진 — 기록 파싱, 단가 계산, SQLite 저장, 집계 (화면 출력 코드 없음)
    src/parser/     기록 읽기 · 검증 · 중복 제거
    src/pricing/    모델별 단가 · 비용 계산 · 캐시 절감액
    src/db/         저장 · 새 기록만 골라 읽는 로직
    src/aggregate/  기간별 · 프로젝트별 · 에이전트별 집계, 연속 사용일
  cli/    # 화면 — 명령어 정의와 표 그리기 (core가 주는 데이터를 보여주기만 함)
apps/
  web/    # (예정) 웹 대시보드 자리

엔진(core)과 화면(cli)을 분리해 둬서, 나중에 웹 대시보드나 팀 서버가 붙을 때 core만 가져다 쓰면 됩니다.

🚀 시작하기

Node.js 20 이상.

npm install -g tokkaebi

tokkaebi today   # 끝!

셸 프롬프트나 tmux에 오늘 지출을 상시 표시하고 싶다면 tokkaebi status --plain을 활용하세요.

git clone https://github.com/Guksu/tokkaebi.git
cd tokkaebi
pnpm install && pnpm build && pnpm test

# 로컬 빌드를 전역 명령으로 (packages/cli에서)
npm link

🗺️ 로드맵

• ✅ CLI — 수집 · 비용 계산 · 오늘/주간/월간 · 히트맵/추이/캐시 분석 · 예산/status · 결산/등급 · 한글 출력
• ⬜ MCP 서버 — Claude에게 "이번 주 얼마 썼어?"라고 물어보기
• ⬜ 팀 모드 — 각자 설치하고 집계 결과만 모아 보는 사내 대시보드 (개인 데이터는 여전히 각자 로컬에)

📄 라이선스

MIT