Claude Code 토큰·비용 추적, toktrack로 끝내기

혹시 Claude Code를 쓰면서 “내가 지금까지 토큰을 얼마나 썼지?” 하고 찜찜했던 적 있으신가요? 생각보다 자주 쓰다 보면 비용이 눈덩이처럼 느껴지는데, 정작 누적 사용량/비용 히스토리를 한눈에 보는 기본 기능이 없다는 점이 불편하더라고요.

최근 레딧에 이런 불편을 정면으로 해결한 도구가 공유됐어요. 이름은 toktrack이고, Claude Code 세션 파일을 스캔해서 비용 대시보드를 만들어주는 무료 오픈소스(MIT) 도구예요.

toktrack가 필요한 이유: 비용이 “보이지” 않으면 관리가 안 돼요

Claude Code를 많이 쓰는 분들은 보통 “이번 작업은 길게 대화했으니 많이 나왔겠지”처럼 감으로만 판단할 때가 많아요. 문제는 이 감이 잘 맞지 않는다는 거예요. 특히 모델을 섞어 쓰거나(예: Opus/ Sonnet/ Haiku), 며칠 동안 누적 사용한 뒤 결제/청구를 보고 놀라는 패턴이 반복되기 쉽습니다.

toktrack는 이 지점을 파고들어요. 세션 파일 기반으로 실제 사용 흔적을 모아 “얼마나 썼는지”를 숫자와 그래프로 보여주죠. 비용이 보이기 시작하면, 어떤 작업이 비싼지/어떤 모델 조합이 합리적인지 같은 판단이 훨씬 쉬워져요.

toktrack 대시보드에서 볼 수 있는 핵심 지표 4가지

이 도구가 보여주는 항목은 딱 ‘관리’에 필요한 것들로 구성돼 있어요. 단순 나열이 아니라, 어디서 비용이 새는지를 찾아주는 형태에 가깝습니다.

• Total tokens and estimated cost(총 토큰/추정 비용)
  지금까지 누적 사용량과 비용을 한 번에 확인할 수 있어요. “이번 달 대략 이 정도 썼구나” 같은 큰 그림이 잡힙니다.

• Per-model breakdown(모델별 breakdown: Opus, Sonnet, Haiku)
  모델별로 얼마나 썼는지 쪼개서 보여줘요. 예를 들어 Opus 비중이 높다면 “정말 그 작업에 Opus가 필요했나?” 같은 최적화 포인트가 바로 보입니다.

• Daily / weekly / monthly trends(일/주/월 추이)
  사용량이 언제 급증했는지 타임라인으로 확인할 수 있어요. 특정 프로젝트 기간, 배포 주간, 장애 대응 시점처럼 비용이 튀는 구간을 찾는 데 유용합니다.

• 52-week cost heatmap(52주 비용 히트맵)
  장기적으로 사용 패턴을 보는 기능이에요. “내가 특정 요일/특정 시즌에 더 많이 쓰는구나” 같은 흐름까지 읽히면, 팀 단위 운영에도 도움이 됩니다.

설치는 npx toktrack 한 줄이면 끝이에요

설치 방식이 가벼운 것도 장점이에요. 터미널에서 한 줄로 실행할 수 있어요.

• 설치/실행: npx toktrack

그리고 흥미로운 포인트가 하나 더 있어요. 작성자 설명에 따르면 toktrack는 Claude Code뿐 아니라 Codex CLI, Gemini CLI에도 동작한다고 해요. 여러 CLI 도구를 섞어 쓰는 분이라면 “비용 추적을 한 곳에서” 가져가고 싶을 때 특히 매력적이죠.

30일 세션 삭제 이슈도 챙겨줘요: 기록은 toktrack가 따로 보관해요

여기서 진짜 실전 포인트가 나와요. Claude Code는 기본 설정상 세션 파일을 30일 후 삭제한다고 해요. 그러면 “지난달 비용을 다시 확인하고 싶은데 자료가 없다” 같은 상황이 생길 수 있죠.

toktrack는 이 문제를 우회합니다. 작성자에 따르면 비용 데이터를 별도로 캐싱(caching, 자주 쓰는 데이터를 따로 저장) 해서, 원본 세션 파일이 삭제돼도 히스토리가 유지된다고 해요.

만약 “원본 세션 파일 자체도 오래 보관하고 싶다”면 설정을 이렇게 바꿀 수 있다고 안내돼 있어요.

// ~/.claude/settings.json
{ "cleanupPeriodDays": 9999999999 }

이건 팀에서 감사를 대비하거나(“우리가 어떤 작업을 언제 했지?”), 개인이 사용 기록을 길게 남기고 싶을 때 꽤 유용한 팁이에요.

마무리: “AI 비용 관리”는 결국 가시화부터 시작해요

toktrack는 거창한 기능보다, 우리가 매번 불편해하던 토큰/비용 가시화를 정확히 해결해주는 도구예요. 특히 모델을 여러 개 섞어 쓰거나, CLI로 매일 작업하는 분이라면 “내 지출이 어디서 생기는지”를 확인하는 것만으로도 운영 방식이 달라질 수 있어요.

한번은 그냥 npx toktrack로 돌려보고, 내 사용 패턴이 어떤지부터 확인해보면 어떨까요?
깃허브는 여기예요: https://github.com/mag123c/toktrack