Claude Code 토큰 사용량, 한눈에 보자 - cctoken

cctoken이 뭔데?

cctoken은 Claude Code 세션의 토큰 사용량을 실시간으로 모니터링하는 CLI 도구다.

Claude Code가 ~/.claude/projects/ 경로에 남기는 세션 로그(JSONL)를 직접 읽어서, 별도의 설정 없이 설치만 하면 바로 사용할 수 있다.

주요 기능

기간별 사용량 조회 — 시간/일/주/월 단위로 토큰 사용량과 비용을 확인
실시간 대시보드 — 5초마다 자동 갱신되는 라이브 모니터링
시간대별 히트맵 — 지난 7일간 언제 가장 많이 사용했는지 시각화
프로젝트별 분석 — 어떤 프로젝트에서 토큰을 가장 많이 소비했는지 막대 그래프로 비교
예산 관리 — 월간 토큰 예산을 설정하고, 소진율과 리셋까지 남은 시간을 추적
모델별 비용 계산 — Opus, Sonnet, Haiku 각 모델의 실제 가격 기반으로 비용 산출

어떤 점이 좋은가

1. 설치만 하면 끝, 설정이 필요 없다

cctoken은 Claude Code가 이미 남기고 있는 세션 로그를 그대로 읽는다. API 키를 입력할 필요도 없고, 별도의 로깅 설정을 켤 필요도 없다. 설치하는 순간부터 지금까지의 모든 사용 기록을 확인할 수 있다.

2. 터미널 안에서 완결

개발하면서 브라우저를 열어 대시보드를 확인할 필요가 없다. 터미널 하나 더 열어서 cctoken watch만 실행하면 실시간으로 토큰이 빠져나가는 걸 볼 수 있다. Rich 라이브러리 기반의 깔끔한 UI로 가독성도 좋다.

3. 예산을 눈으로 확인

Claude Code의 Max plan이든 팀 플랜이든, 토큰에는 한도가 있다. cctoken은 월간 예산을 설정하면 기간별로 비례 배분된 예산 대비 현재 사용량을 프로그레스 바로 보여준다. 초록 → 노랑 → 빨강으로 색이 변하니, 감각적으로 "아, 좀 아껴 써야겠다"를 느낄 수 있다.

4. 프로젝트별로 어디서 많이 썼는지 보인다

여러 프로젝트를 오가며 Claude Code를 쓸 때, 어떤 프로젝트가 토큰을 가장 많이 잡아먹는지 한눈에 비교할 수 있다. 작업 디렉토리 기반으로 자동 분류되기 때문에 따로 태그를 달거나 할 필요가 없다.

5. 모델별 실제 비용을 알 수 있다

Opus, Sonnet, Haiku 각 모델의 공식 가격(입력/출력/캐시)을 기반으로 실제 비용을 계산해준다. 캐시 토큰과 일반 토큰을 분리해서 보여주기 때문에, 캐시가 얼마나 효율적으로 작동하고 있는지도 파악할 수 있다.

설치 방법

Homebrew (추천)

brew tap HongChaeMin/cctoken
brew install cctoken

가장 간단한 방법이다. macOS나 Linux에서 Homebrew를 사용하고 있다면 두 줄이면 끝난다.

pip

pip install git+https://github.com/HongChaeMin/cctoken.git

Python 환경에서 직접 설치할 수도 있다. Python 3.9 이상이 필요하다.

소스에서 설치

git clone <https://github.com/HongChaeMin/cctoken.git>
cd cctoken
pip install -e .

직접 코드를 수정하거나 기여하고 싶다면 이 방법을 사용하면 된다.

사용법

실시간 대시보드

cctoken
# 또는
cctoken watch

기본 명령어다. 실행하면 5초마다 자동 갱신되는 대시보드가 뜬다. 시간/일/주/월별 토큰 카드, 소비 속도, 프로젝트별 순위가 한 화면에 보인다.

기간별 상세 조회

cctoken hour    # 최근 5시간 블록
cctoken today   # 오늘
cctoken week    # 이번 주
cctoken month   # 이번 달

각 기간별로 모델 분포, 예산 대비 사용량, 비용 등을 상세하게 확인할 수 있다.

사용 추이 히트맵

cctoken trend

지난 7일간의 시간대별 사용량을 히트맵으로 보여준다. 내가 주로 언제 Claude Code를 많이 쓰는지 패턴을 파악할 수 있다.

예산 설정

cctoken budget set 10000000   # 월간 토큰 예산 1천만 토큰으로 설정
cctoken budget reset-day 15   # 매월 15일에 리셋

설정은 ~/.cctoken.json에 저장되며 한 번 설정하면 계속 유지된다.

Claude Code와 연동하기

세션이 끝날 때마다 자동으로 토큰 요약을 보고 싶다면, Claude Code의 Stop hook을 활용할 수 있다.

~/.claude/settings.json에 다음을 추가하면 된다:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "cctoken today"
          }
        ]
      }
    ]
  }
}

이렇게 하면 Claude Code 세션을 종료할 때마다 오늘의 토큰 사용 요약이 자동으로 출력된다.

기술 스택

Python — 메인 언어 (3.9+)
Rich — 터미널 UI 렌더링 (표, 패널, 프로그레스 바, 스파크라인 등)
Homebrew — 패키지 배포

마무리

Claude Code를 본격적으로 사용하다 보면, 토큰 사용량 관리는 선택이 아니라 필수가 된다. cctoken은 그 과정을 최대한 자연스럽고 간편하게 만들어준다. 설치 한 번이면 끝이고, 터미널에서 벗어날 필요도 없다.

관심 있다면 GitHub에서 확인해보자.

GitHub: https://github.com/HongChaeMin/cctoken
Homebrew Tap: https://github.com/HongChaeMin/homebrew-tap![](https://cdn.hannah-log.site/cdn/blog/1773378011071_image_small.jpg)

목차

태그