나는 비용을 걱정하지 말라고 Claude Code가 말했기 때문에 kerf-cli를 만들었다

Source: Dev.to

몇 주 전, Claude Code에 로그인하고 /cost를 입력했더니 다음과 같은 답변을 받았습니다:

With your Claude Max subscription, no need to monitor cost.

이틀 뒤, 저는 단 하루 아침에 **91 %**의 주간 한도를 사용해 버렸습니다. 어떤 세션인지, 어떤 프로젝트인지, 어떤 모델이 원인인지 전혀 알 수 없었습니다. ccusage(아주 유용함)를 사용해 보았고 총합은 확인했지만, 다음과 같은 질문을 하고 싶었습니다:

• “내 프로젝트 중 어느 것이 Opus 토큰을 불필요하게 소모하고 있나요?”
• “지난 30 일 동안 실제 캐시 히트 비율은 얼마인가요?”

그 답변은 찾을 수 없었습니다.

그래서 저는 kerf‑cli를 만들었습니다 — Claude Code용 로컬 우선 비용 인텔리전스 도구입니다. 이 글에서는 kerf‑cli가 왜 존재하게 되었는지, 무엇을 하는지, 그리고 그 과정에서 Claude Code 청구에 대해 배운 점을 공유합니다.

실제 문제

Anthropic은 방대한 데이터를 제공하지만 그 위에 거의 분석 도구가 없습니다. 모든 Claude Code 세션은

~/.claude/projects//.jsonl

에 기록되며, 입력, 출력, cache_read, cache_creation, 모델, 타임스탬프, git 브랜치와 같은 전체 토큰 분해 정보를 포함합니다. 데이터는 풍부하지만, 그 위에 있는 도구는 부족합니다.

시작했을 때 존재하던 것

내가 원했지만 얻지 못한 것

1. SQL로 쿼리할 수 있는 지속적인 분석 레이어
2. 경고가 아닌, 한도를 초과하면 Claude Code를 차단하는 실제 예산 집행
3. 구체적인 최적화 권장 사항 – 예: “이 12개의 세션을 Opus에서 Sonnet으로 전환하면 월 $140을 절감할 수 있습니다.”

Kerf 작동 방식

Kerf는 commander, ink, better-sqlite3를 기반으로 한 TypeScript CLI입니다. 아키텍처는 매우 단순합니다:

1. Ingest Claude Code의 기존 JSONL 세션 파일을 로컬 SQLite 데이터베이스에 가져옵니다.
2. Sync – kerf sync는 한 번 실행하면 지금까지 가진 모든 세션을 가져오고; 이후 동기화는 증분 방식으로(변경된 파일만 다시 파싱) 진행됩니다.
3. Query – 모든 명령과 웹 대시보드는 해당 SQLite DB를 직접 쿼리하므로 모든 작업이 빠릅니다.

중요한 명령어들

kerf summary

빵과 버터 – “내가 뭘 썼지?”

$ kerf summary --period week --by-project

For week (Apr 1 → Apr 7):
  Total cost: $178.04
  Sessions:   25
  Tokens:     454.0M
  Cache hit:  98%

By project:
  projects   $117.00 (66%) 5 sessions
  subagents  $42.50  (24%) 14 sessions
  kerf       $14.54  (8%)  4 sessions

kerf query

내가 주로 나를 위해 만든 SQL 탈출구:

$ kerf query "SELECT date(timestamp) AS day,
                     ROUND(SUM(cost_usd), 2) AS cost
              FROM messages
              WHERE timestamp > date('now', '-7 days')
              GROUP BY day
              ORDER BY day DESC"

결과:

• --examples는 복사할 수 있는 유용한 쿼리 열두 개를 출력합니다.
• --schema는 데이터베이스 스키마를 출력합니다.
• 쓰기는 차단됩니다 – SELECT 문만 허용됩니다.

kerf efficiency

실제로 비용을 절감해 주는 명령어. 매주 월요일 아침에 사용하는 명령어입니다.

결과: 분석기가 대부분의 Opus 세션이 Sonnet에서 충분히 수행될 수 있는 패턴(파일 편집, 작은 리팩터링, 의존성 업데이트)임을 지적했습니다. 이러한 워크플로를 전환함으로써 월간 Claude 비용의 의미 있는 부분을 품질 차이 없이 절감했습니다.

kerf budget + kerf init --enforce-budgets

핵심 기능.

$ kerf budget set 50 --period weekly   # 주당 $50 한도 설정
$ kerf init --enforce-budgets          # Claude Code PreToolUse 훅 설치

이 훅은 모든 툴 호출 전에 kerf budget check을 실행합니다. 예산을 초과하면 훅이 종료 코드 2를 반환하고 Claude Code가 해당 동작을 차단합니다.

차이점: 다른 도구들은 경고만 하지만, Kerf는 강제합니다.

kerf dashboard

시각적인 사람들을 위한 로컬 웹 UI입니다. http://localhost:3847에서 열리며 SQLite 기반이라 쿼리 시간이 100 ms 미만입니다. 주요 기능:

• 예산, 효율성, 캐시 세 가지 “핵심‑기능” 카드가 전면에 배치
• 드릴‑다운이 가능한 정렬 가능한 세션 테이블
• 모델별 비용‑시간 누적 차트
• 인증 필요 없음, 클라우드 필요 없음, 데이터가 머신을 떠나지 않음

위는 이 글 상단에 있는 스크린샷입니다.

Claude Code 청구에 대해 배운 점

JSONL 파일을 오래 들여다보며 알게 된 몇 가지 눈에 띄지 않는 점:

1. 캐시 읽기가 전체 비용의 60 %–80 %를 차지할 수 있습니다.
   캐시 읽기는 표준 입력 요금의 10 %로 청구되며, 매 턴마다 50 K 토큰을 캐시하고 매 메시지마다 이를 읽는다는 사실을 깨닫기 전까지는 저렴하게 들립니다. CLAUDE.md를 최적화하고 캐시 무효화를 줄이는 것이 제가 발견한 가장 큰 단일 레버였습니다.

2. Opus가 기본값이며 거의 필요하지 않습니다.
   kerf efficiency를 한 달 데이터에 실행해 본 결과, 내 Opus 토큰의 **90 %**가 복잡도 신호가 없는 세션에 사용되었습니다(디버깅, 아키텍처 결정, 대규모 리팩터링 없이 파일 편집 및 작은 수정만). 이러한 워크플로를 Sonnet으로 전환하면 품질을 희생하지 않으면서도 상당히 절감할 수 있었습니다.

기술적 인사이트

1. Sonnet으로 전환하면 비용이 4배 절감되며 측정 가능한 품질 저하가 없습니다.
2. Claude Code의 JSONL 스트림은 부분 사용량 업데이트를 제공합니다.
   파싱할 때 중복된 메시지 ID가 있을 경우 최신값이 아니라 각 필드별 최대값을 유지해야 합니다. 제 v2.1 파서는 최신 항목을 유지했기 때문에 입력 토큰을 과소 계산했으며, 최종 제로 입력 청크가 이전 청크의 실제 숫자를 덮어썼습니다. 출시 전에 수정했지만, 이 로그를 파싱하는 사람이라면 누구나 마주할 수 있는 미묘한 함정입니다.
3. 5시간 청구 윈도우는 실제로 존재하지만, Anthropic은 이를 명확히 공개하지 않습니다.
   Max 구독자는 일일 할당량이 아니라 순환하는 5시간 윈도우를 기준으로 청구됩니다. 이를 추적하지 않으면 세션 중간에 윈도우가 넘어가면서 놀랄 수 있습니다.

Technical decisions I’d defend

• JSON 파일보다 SQLite.
  JSON은 ccusage의 “한 번 읽고, 계산하고, 버리는” 모델에 적합합니다. 분석 레이어에서는 100 ms 미만의 쿼리, 조인, 집계, 그리고 스키마 마이그레이션 스토리가 필요합니다. better-sqlite3를 통한 SQLite가 올바른 도구입니다.

• 클라우드 우선보다 로컬 전용.
  클라우드 동기화를 추가하면 인증, 스토리지, 프라이버시 제어, GDPR 준수, 그리고 비즈니스 모델이 필요해지는데, 이는 “내 돈이 어디로 갔는지 보여줘”라는 기본 사용 사례에 전혀 도움이 되지 않습니다. Kerf는 의도적으로 로컬‑퍼스트입니다. 호스팅된 팀 티어는 로드맵에 있지만 언제나 선택 사항으로 남을 것입니다.

• 터미널 UI를 위한 Ink.
  터미널에서 React 컴포넌트를 사용하는 것은 처음에 어색할 수 있지만, 컴포저블한 구조가 그만한 가치가 있습니다.

• 강제 메커니즘으로서 Hooks.
  Claude Code는 네이티브 훅 시스템을 제공합니다. 훅을 사용하면 Kerf가 Claude Code의 트래픽을 가로채거나 프록시할 필요 없이, Claude Code가 이미 발생시키는 이벤트에 응답하기만 하면 됩니다.

다음 단계

v1은 한 가지를 잘 하는 데 집중합니다: 개별 개발자를 위한 Claude Code 가시성. 앞으로의 로드맵은 다음과 같습니다:

• v2.x: Cursor 및 Codex 지원
• v2.x: 예산 임계값에 대한 Slack/Discord 알림
• v2.x: PR에 대한 비용 게이트를 위한 GitHub Actions 통합
• v3.x (paid team tier): 클라우드 동기화, 팀 집계, SSO

v1이 완전히 견고해질 때까지는 그 어떤 것도 출시되지 않을 것입니다. CLI는 언제나 무료이며 MIT‑licensed입니다.

Try it

npm install -g kerf-cli
kerf sync
kerf summary

• GitHub:
• Show HN discussion:

Claude Code에서 청구서가 예상과 달랐던 경험이 있다면, 댓글로 알려 주세요. 이상한 패턴을 많이 볼수록 분석기가 더 좋아집니다.