Claude Code가 이미 디스크에 남기고 있는 토큰 사용량을 터미널에서 보는 대시보드입니다.

지금까지 열어본 모든 프로젝트를 쏟아내지 않고, 지금 서 있는 디렉터리 — Claude가 여기서 무엇을 했는지 — 를 보여줍니다. 의존성도, API 호출도, 별도 계정도 없습니다. ~/.claude에 남은 기록만 읽습니다.

 TokenMeter  전체  전체 프로젝트                                갱신 07:40:16 
 전체 프로젝트                                  요청 81 / 프로젝트 1 / 세션 1 
┌─ 사용량 ──────────────────────────────────────────────── 한도 2분 전 조회 ─┐
│ 5시간 한도   ████████████░░░░░░░░░░░░░░░░░░░░░░░░  34% 3시간 11분 후 초기화│
│   09-22 07:00 - 12:00 출력          840 읽기       114.0k 히트율      98.8%│
│ 주간 한도    ██████████████████████░░░░░░░░░░░░░░  61% 3일 9시간 후 초기화 │
│   09-15 - 09-22       출력        89.0k 읽기        13.3M 히트율      98.9%│
└────────────────────────────────────────────────────────────────────────────┘
┌─ 일자별 ─────────────────────────────────────────────────── 09-16 - 09-22 ─┐
│ 날짜  입력 + 캐시 + 출력                                               합계│
│ 09-16 █████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░   811.7k│
│ 09-17 ····························································        -│
│ 09-18 █████████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░     2.3M│
│ 09-19 ████████████████████████████████████████████████████████████     5.6M│
│ 09-20 ███████████████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░     2.9M│
│ 09-21 ██████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░     1.7M│
│ 09-22 █░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░   116.2k│
└────────────────────────────────────────────────────────────────────────────┘
┌─ 모델별 ─────────────────────────────────────────┐┌─ 캐시 ─────────────────┐
│ opus-5       ██████████████████    81 요청  98.9%││ 히트율            98.9%│
└──────────────────────────────────────────────────┘│ 절감              13.3M│
                                                    │ 캐시쓰기         142.1k│
                                                    └────────────────────────┘
 [1]전체 [2]세션 [3]일자별  [r]새로고침 [l]언어 [q]종료

설치

pip install git+https://github.com/aidevksh/tokenmeter

그다음 아무 프로젝트 디렉터리에서:

tokenmeter

설정은 이게 전부입니다. pip이 tokenmeter 명령을 PATH에 올려줍니다 — Windows에서는 tokenmeter.exe라서 PowerShell과 cmd 양쪽에서 되고, macOS·Linux에서는 실행 스크립트가 생깁니다.

다른 설치 방법

고쳐가며 쓰려면 클론해서:

git clone https://github.com/aidevksh/tokenmeter
cd tokenmeter
pip install -e .

격리해서 쓰려면 pipx:

pipx install git+https://github.com/aidevksh/tokenmeter

설치가 아예 싫으면, 클론한 디렉터리에서 이것도 항상 됩니다:

python -m tokenmeter

설치 후에도 명령을 못 찾으면 pip의 스크립트 디렉터리가 PATH에 없는 경우입니다. 아래 명령이 그 경로를 알려줍니다:

python -c "import sysconfig; print(sysconfig.get_path('scripts'))"

필요한 것은 Python 3.8 이상, 그리고 Claude Code를 한 번이라도 돌린 기록. 그 외에는 없습니다 — 전부 표준 라이브러리로만 만들었습니다.

사용법

tokenmeter                 # 현재 디렉터리
tokenmeter ~/src/thing     # 다른 디렉터리
tokenmeter --all           # 전체 프로젝트
tokenmeter --once          # 한 번만 출력하고 종료

화면
전체 계정 한도와 해당 구간의 토큰 합계, 일자별 막대, 모델별, 캐시
프로젝트 프로젝트당 한 줄 (스코프에 둘 이상일 때만 나타남)
세션 제목으로 보는 세션 목록, 선택한 세션 상세, 처리량 차트
일자별 날짜별 표: 요청, 출력, 캐시 읽기/쓰기, 합계

세션은 세션 ID가 아니라 Claude가 붙인 제목으로 나열됩니다. 방향키로 목록을 움직이면 상세 패널이 따라옵니다.

단축키

1..4      화면 전환              s     정렬 변경 (프로젝트, 세션)
위/아래   선택 (j/k 도 됨)       r     로그 다시 읽기
enter     프로젝트 파고들기      l     한국어/영어 전환
esc       뒤로                   q     종료

문자 단축키는 두벌식 자판도 함께 받습니다. IME가 한글 상태여도 r, q, l이 그대로 동작합니다 — ㄱ, ㅂ, ㅣ가 같은 명령에 닿으므로 영문으로 전환했다가 돌아올 필요가 없습니다.

옵션

--all              디렉터리 하나가 아니라 전체 프로젝트
--root 경로        기록 루트 (기본값: ~/.claude/projects)
--lang en|ko       감지된 언어를 무시하고 지정
--screen 이름      시작 화면: overview | projects | sessions | daily
--days N           차트에 그릴 기간 (기본값 14일)
--interval 초      실시간 갱신 주기 (기본값 1초)
--once             한 프레임만 출력하고 종료 (파이프로 넘길 때 자동)
--no-color         NO_COLOR 환경변수도 따릅니다
--ascii            박스 문자 대신 +-| 사용

실시간

화면은 기본 1초마다 알아서 갱신됩니다. 기록이 실제로 바뀌었을 때만 다시 읽으므로, 놀고 있는 대시보드는 틱당 파일 수만큼의 stat만 씁니다. 마지막으로 읽은 시각은 헤더에 표시됩니다.

한도

전체 화면의 퍼센트는 실제 계정 한도입니다 — Claude Code 사이드바의 Session (5hr), Weekly (7 day), 그리고 모델별 한도에 나오는 바로 그 숫자입니다. 기록에서 계산한 값이 아닙니다. 기록에는 한도 정보가 전혀 없고, 이 값은 Claude Code 자신의 ~/.claude.json에 있는 cachedUsageUtilization 에서 읽습니다.

여기서 두 가지가 따라옵니다.

  • 게이지는 계정 전체이고, 그 아래 토큰 숫자는 아닙니다. 들여쓴 줄의 숫자는 이 디렉터리(또는 --all)의 합계입니다. 어느 디렉터리인지는 헤더에 적혀 있습니다.
  • 값은 Claude Code가 남겨둔 시점 기준입니다. Claude Code가 API와 통신할 때 이 캐시를 갱신하므로, 패널 태그에 그 값이 얼마나 오래됐는지 표시합니다. 캐시가 아예 없으면 지어내는 대신 게이지를 그리지 않습니다.

각 게이지는 채워질수록 초록에서 노랑을 거쳐 빨강으로 물들기 때문에, 한도에 얼마나 가까운지 한눈에 읽힙니다.

색

한 줄 안에서 절대 섞이지 않는 두 축입니다.
판단 초록 → 호박 → 빨강: 캐시 건강도, 그리고 한도 게이지
토큰 종류 시안 출력 · 파랑 캐시읽기 · 주황 캐시쓰기

구조선은 전부 회색입니다. --no-color와 NO_COLOR로 끌 수 있습니다.

언어

아래 순서로 결정되며, 먼저 걸리는 것이 이깁니다.

  1. --lang
  2. ~/.tokenmeter.json (l 키를 누르면 기록됨)
  3. $TOKENMETER_LANG
  4. $LC_ALL, $LC_MESSAGES, $LANG
  5. OS 설정 — Windows에서는 위 환경변수가 보통 비어 있으므로 GetUserDefaultUILanguage()를 읽습니다
  6. 영어

데이터에 관하여

토큰 수치는 ~/.claude/projects/<cwd-슬러그>/<세션ID>.jsonl의 type: "assistant" 줄, message.usage 필드에서 읽습니다. 한도 퍼센트는 ~/.claude.json(또는 $CLAUDE_CONFIG_DIR/.claude.json)의 cachedUsageUtilization.utilization.limits에서 읽습니다. 둘 다 읽기만 합니다.

  • 요청은 requestId로 중복 제거합니다. 한 요청이 여러 줄에 걸쳐 기록될 수 있어서, 줄 수로 세면 모든 합계가 두 배 가까이 부풀려집니다.
  • cwd는 프로젝트가 아닙니다. 세션 도중 cd를 하면 바뀌므로, 기록 디렉터리를 키로 삼고 그 안에서 가장 짧은 cwd로 표시 이름을 복원합니다. 덕분에 슬러그가 뭉개버린 한글 이름도 되살아납니다.
  • 5시간 블록은 첫 요청 시각을 정시로 내려 잡습니다 — 사용량 제한 창과 같은 모양입니다.
  • <synthetic> 메시지는 건너뜁니다. 사용량이 없는 오류 자리표시자입니다.
  • 세션 제목은 대화가 진행되는 동안 Claude가 기록하는 ai-title에서 가져옵니다. 마지막 것이 이기고, 없으면 첫 사용자 프롬프트를 씁니다.
  • 비용은 표시하지 않습니다. 계산에 필요한 값은 기록에 있습니다. usage.cache_creation의 5분/1시간 캐시 쓰기 구분까지 들어 있습니다.

레이아웃

글자 폭은 문자 개수가 아니라 터미널 칸 수로 잽니다 — 한글과 CJK는 두 칸을 차지합니다. 모든 열 위치는 패널 폭에서 계산하므로, 같은 박스가 두 언어 모두에서, 그리고 60칸부터 어떤 터미널 크기에서도 유지됩니다.

박스 문자와 블록 문자는 동아시아 애매(ambiguous) 폭입니다. 요즘 터미널은 한 칸으로 그리지만, 그렇지 않게 설정돼 있다면 --ascii를 쓰세요.

TODO

  • Codex 지원. OpenAI Codex의 세션 로그도 Claude Code와 나란히 읽어서, 대시보드 하나로 두 도구를 모두 보게 할 예정입니다.
  • 비용. 믿을 만한 단가 표가 마련되면.

라이선스

Apache 2.0. Copyright 2026 aidevksh.