stormzhang/token-tracker

Claude Code & Codex 本地 token 追踪 — 状态栏（Codex 业界首创伪 statusline）、GitHub 风格热力图、多模型成本分析。 | Local token tracker for Claude Code & Codex — status line (industry-first Codex faux statusline), GitHub-style heatmap, multi-model cost analysis

Token Tracker(tt)

하는 일 – Token Tracker는 Claude Code, Codex, Kimi Code 세 가지 인기 코드 어시스턴트 에이전트를 사용할 때 소비하는 AI 모델 토큰의 양을 추적하는 로컬 명령줄 유틸리티입니다. 에이전트의 로컬 트랜스크립트 파일을 읽고, 토큰 수를 집계하고, 금전적 비용을 추정하고, 여러 편리한 위치에 정보를 표시합니다:

에이전트 자체 터미널 UI 내부에 표시되는 사용자 지정 StatusLine,
분할 창(iTerm2, Ghostty, tmux)에 고정할 수 있는 라이브 "사이드바" 패널,
tt daily, tt weekly 등으로 호출할 수 있는 일일/주간/월간 보고서 세트.

모든 데이터는 사용자 머신에만 남습니다. 네트워크 업로드는 없습니다.

주요 기능(README에서)

기능	작동 방식
세 에이전트 통합 추적	Claude Code JSONL 로그, Codex JSONL + SQLite, Kimi Code wire JSONL을 읽습니다. 토큰은 세션 및 모델별로 합산됩니다.
StatusLine 통합	• Claude Code – 공식 StatusLine API(4줄 레이아웃) 사용. • Codex – Stop 후크를 통해 일반 텍스트 두 줄 삽입(최신 버전에서는 색상 없음). • Kimi Code – 공식 `status_line` 인터페이스(단색 줄) 사용.
라이브 사이드바(`tt sidebar`)	5초마다 새로 고쳐지는 좁은 패널로, 활성 세션(최근 5시간), 세 도시 시계, 최근 프롬프트, 상태 표시등, 마지막 AI 응답에서 추출한 "다음 단계" 제안을 나열합니다. 줄을 클릭하면 해당 iTerm2/tmux 패널로 이동합니다.
현재 세션의 자동 분할 화면	Codex 또는 Kimi Code 세션 내에서 `$tt-sidebar`를 입력하면 도구가 오른쪽에 1/3 너비 패널을 열고 해당 세션의 전체 프롬프트 기록을 표시합니다.
쿼터 모니터링	일반적인 5시간 및 7일 제한에 대한 슬라이딩 윈도우 사용량을 진행 표시줄 및 재설정 카운트다운과 함께 표시합니다.
비용 분석	LiteLLM의 가격 데이터와 주요 모델(Claude Opus, Sonnet, Gemini, Grok, Kimi, GLM, Qwen 등 중국 모델)을 포괄하는 내장 폴백 테이블을 사용합니다. 세션별, 일일, 주간, 월간 비용을 계산합니다.
테마 출력	6가지 색상 테마(Catppuccin 계열, Nord, Dracula). 테마는 CLI 보고서와 에이전트의 상태 줄 모두에 적용됩니다.
제로 구성 감지	첫 실행 시 설치된 에이전트를 자동으로 감지하고 로컬 데이터 디렉토리를 읽습니다.
프라이버시 우선	데이터는 어디로도 전송되지 않습니다. 모든 것은 `~/.config/token-tracker` 아래에 로컬로 저장됩니다.

일반적인 워크플로

설치 – 원라이너 curl … | bash를 실행합니다. 스크립트는 최상의 설치 프로그램(uv, pipx 또는 개인 venv)을 선택합니다.
설정 – tt setup은 짧은 대화형 마법사(언어, 테마, 각 에이전트의 상태 줄을 인계받을지 여부)를 안내합니다.
사용 –
- tt 또는 tt daily는 지난 1년간의 토큰 사용량에 대한 GitHub 스타일 히트맵을 표시합니다.
- tt status는 오늘의 합계와 쿼터 백분율을 제공합니다.
- tt weekly / tt monthly는 막대 차트 보고서를 생성합니다.
- tt sidebar는 라이브 패널을 엽니다. tt sidebar --once는 단일 스냅샷을 출력합니다.
- Codex/Kimi 세션 내에서 $tt-sidebar를 입력하면 자동 분할 화면 보기가 나타납니다.
조정 – tt theme set <name>으로 테마를 변경하거나 tt setup을 다시 실행하여 상태 줄 구성을 수정합니다.
제거 – tt unsetup은 후크/스킬을 제거하고 이전 사용자 지정 상태 줄을 복원합니다.

누구에게 유용한가요?

AI 코딩 어시스턴트를 자주 사용하는 개발자 – 예상치 못한 청구서를 피하기 위해 토큰 소비를 주시해야 하는 사람.
쿼터를 공유하는 팀(예: 5시간 슬라이딩 윈도우) – 한도에 얼마나 가까운지 빠르게 시각적 단서를 원하는 사람.
깔끔한 터미널 UI를 좋아하는 사람 – 사이드바와 상태 줄은 별도의 대시보드를 열지 않고도 한눈에 보는 메트릭을 제공합니다.

제한 사항 / 고려 사항

지원되는 세 에이전트에서만 작동합니다. 다른 LLM 프런트엔드는 무시됩니다.
모든 비용 계산은 정적 가격 테이블에 의존합니다. 제공자가 가격을 변경하면 내장 데이터를 업데이트해야 합니다.
"다음 단계" 제안은 규칙 기반이며 모델에서 생성되지 않습니다.
Windows에서 사이드바는 콘솔의 GBK 인코딩에 적응하지만 일부 색상 충실도는 줄어들 수 있습니다.

빠른 참조(명령)

tt setup          # 초기 구성, 상태 줄 후크 및 사이드바 스킬 설치
tt               # `tt daily`와 동일 – 연간 히트맵
tt daily          # 토큰 사용량 히트맵
tt status         # 오늘의 합계 + 쿼터 막대
tt weekly         # 주간 보고서(비용, 토큰, 추세)
tt monthly        # 월간 보고서
tt sessions       # 최근 세션 나열, 정렬 가능
tt sidebar        # 활성 세션이 있는 라이브 패널
tt sidebar --once# 단일 스냅샷
tt theme …       # 테마 표시/목록/미리보기/설정
tt unsetup        # 삽입된 모든 후크/스킬 제거

결론 – Token Tracker는 개발자가 AI 코딩 에이전트가 소비하는 토큰 수, 해당 토큰의 비용, 쿼터 한도에 가까워지고 있는지 여부를 터미널에서 모두 구체적으로 파악할 수 있게 해주는 진정한 오픈 소스 Python 도구입니다.