주요 콘텐츠로 건너뛰기
AI 튜토리얼

tokentab으로 로컬 AI 토큰 사용량 및 비용 추적

tokentab 설치 방법, 로컬 세션 로그에서 AI 토큰 사용량과 예상 비용을 분석하는 방법, 날짜 또는 프로젝트별 보고서 필터링, 비공개 웹 대시보드 열기, 결과 해석 및 다른 제공업체를 추가해 프로젝트 확장하는 방법을 알아봅니다.

약 10분 소요
tokentab으로 로컬 AI 토큰 사용량 및 비용 추적

tokentab의 기능

tokentab은 코딩 어시스턴트가 토큰을 어떻게 사용하고 예상 비용을 어떻게 누적하는지 파악할 수 있도록 돕는 로컬 리포팅 도구입니다. 지원되는 도구가 이미 컴퓨터에 저장한 세션 로그를 읽은 다음, 모델, 제공업체, 프로젝트, 날짜 및 추정된 활동 유형별로 사용량을 그룹화합니다.

계정이나 API 키가 필요하지 않습니다. 모든 처리는 컴퓨터에서 이루어지며, tokentab은 세션 정보를 업로드하거나 가격 정보를 제공하는 서비스에 접속하지 않습니다.

tokentab 웹 대시보드

지원 도구 및 로그 위치

현재 tokentab에는 다음 세 가지 도구를 위한 파서가 구현되어 있습니다.

  • Claude Code: ~/.claude/projects/**/*.jsonl
  • Codex: ~/.codex/sessions/**/rollout-*.jsonl
  • Gemini CLI: ~/.gemini/tmp/**/session-*.json

Cursor용 제공업체 항목은 있지만 파서는 아직 완성되지 않았습니다. 지원되는 도구가 설치되어 있지 않으면 tokentab은 해당 도구를 건너뜁니다. 따라서 리포트에는 컴퓨터에서 로그를 사용할 수 있는 도구의 데이터만 포함됩니다.

주요 기능

  • 기존 로컬 세션 로그에서 토큰 수를 직접 읽습니다.
  • 로컬에서 직접 관리하는 가격표를 사용해 비용을 추정합니다.
  • 제공업체, 모델, 프로젝트, 날짜 및 활동별로 데이터를 그룹화합니다.
  • 일별, 월별, 전체 기간 및 사용자 지정 날짜 범위를 지원합니다.
  • 터미널 표 또는 기계가 읽을 수 있는 JSON을 생성합니다.
  • localhost에만 연결되는 브라우저 대시보드를 제공합니다.
  • 출력을 파이프로 전달하면 터미널 색상을 자동으로 제거합니다.
  • 웹 프레임워크를 사용하지 않으며, 대시보드는 Python 표준 라이브러리의 HTTP 서버에서 실행됩니다.

유일한 서드파티 의존성은 터미널 표를 렌더링하는 Rich입니다. 파싱, JSON 처리 및 로컬 웹 서버는 Python 표준 라이브러리를 사용합니다.

tokentab 설치

일반 설치

저장소를 복제하고 해당 디렉터리로 이동한 다음, 활성 Python 환경에 패키지를 설치합니다.

git clone https://github.com/damejan80/tokentab
cd tokentab
pip install .
python cli.py

설치가 완료되면 경로에 tokentab 명령이 추가됩니다. 이후에는 설치된 명령을 직접 실행할 수 있습니다.

tokentab

편집 가능한 소스 설치

코드를 살펴보거나 수정할 계획이라면 편집 가능 모드로 설치합니다.

git clone https://github.com/damejan80/tokentab
cd tokentab
pip install -e .
tokentab

편집 가능 설치를 사용하면 명령이 작업 사본에 연결되므로 패키지를 다시 설치하지 않아도 로컬 코드 변경 사항이 적용됩니다.

첫 리포트 실행

저장소 디렉터리에서 옵션 없이 CLI를 실행합니다.

python cli.py

기본 리포트는 감지된 모든 제공업체와 프로젝트를 대상으로 최근 7일을 다룹니다. 명령을 설치한 경우 동일한 실행 방법은 다음과 같습니다.

tokentab

tokentab은 제공업체가 이미 사용 중인 로그 디렉터리를 읽으므로 계정 설정이나 자격 증명 구성이 필요하지 않습니다. 지원되는 로그가 없으면 포함할 사용량도 없습니다.

시간별 사용량 필터링

오늘의 활동

python cli.py -today

현재 달력상의 월

python cli.py -month

사용 가능한 전체 기록

python cli.py -p all

특정 날짜 범위

python cli.py --from 2026-06-01 --to 2026-06-15

사용자 지정 범위는 사용량을 스프린트, 청구 기간, 실험 또는 기타 정해진 기간과 일치시킬 때 유용합니다.

제공업체 또는 프로젝트별 필터링

Claude 사용량만 표시하려면 제공업체 필터를 전달합니다.

python cli.py --provider claude

특정 프로젝트에 집중하려면 프로젝트 이름을 사용합니다.

python cli.py --project myapp

이러한 필터를 사용하면 특정 코드베이스나 도구의 비용을 전체 활동에서 분리해 확인할 수 있습니다.

기계가 읽을 수 있는 JSON 내보내기

다른 프로그램에서 리포트를 사용해야 할 때는 --json을 사용합니다.

python cli.py --json

예를 들어 jq가 설치되어 있다면 JSON을 파이프로 전달해 형식을 지정하거나 추가로 처리할 수 있습니다.

python cli.py --json | jq .

tokentab은 일반 출력을 파이프로 전달할 때 터미널 색상을 자동으로 제거하므로 ANSI 이스케이프 코드 없이 리포트를 풀 리퀘스트, 채팅 메시지, 파일 또는 다른 명령에 쉽게 붙여 넣을 수 있습니다.

로컬 웹 대시보드 사용

다음 명령으로 브라우저 인터페이스를 시작합니다.

python cli.py -web

tokentab은 http://localhost:4747을 열고 데이터를 월별 명세서처럼 표시합니다. 상단에는 총액이, 아래에는 항목별 세부 정보가 표시됩니다.

대시보드는 결과를 캐시하지 않고 요청할 때마다 디스크에서 로그를 읽으므로 별도의 데이터베이스를 유지하지 않아도 새로 기록된 세션이 표시될 수 있습니다. localhost에만 연결되며 데이터를 업로드하지 않습니다. 또한 외부 글꼴 서비스를 사용하지 않으므로 네트워크가 연결되지 않은 상태에서도 인터페이스를 사용할 수 있습니다.

다른 포트를 선택하려면 --port를 사용합니다. 브라우저를 자동으로 열지 않고 서버를 시작하려면 --no-open을 추가합니다.

python cli.py -web --port 8080 --no-open

토큰 및 비용 계산 이해하기

토큰 수

토큰 총합은 텍스트에서 추정한 값이 아니라 지원되는 도구의 로그에서 직접 가져옵니다. tokentab은 캐시 보고 방식의 차이도 반영합니다. Claude는 캐시 읽기와 쓰기를 별도로 기록하지만, Gemini는 캐시된 토큰을 포함한 입력을 보고합니다. tokentab은 동일한 토큰에 이중으로 요금이 부과되지 않도록 필요한 경우 캐시된 부분을 제외합니다.

모델 가격

가격은 tokentab/pricing/prices.py에 토큰 100만 개당 달러 단위로 로컬 저장됩니다. 이 도구는 네트워크에서 실시간 가격을 요청하는 대신 의도적으로 정적 표를 사용합니다.

모델 매칭은 퍼지 방식으로 이루어지므로 claude-opus-4-6-20260514와 같은 날짜가 포함된 모델 식별자는 더 일반적인 claude-opus-4-6 항목과 일치할 수 있습니다. 모델이 $0.00 비용으로 표시된다면 이름이 표와 일치하지 않았을 가능성이 큽니다. CLI는 모델이 무료라고 조용히 가정하는 대신 이 상태를 보고합니다.

가격은 최선의 추정치입니다. 공급업체가 가격을 변경하거나 아직 인식되지 않은 모델 이름을 도입하면 로컬 표를 업데이트하세요.

활동 카테고리

코딩, 디버깅, 리팩터링, 테스트, 채팅, 탐색과 같은 활동 라벨은 사용된 도구와 세션의 첫 메시지에 사용된 표현을 바탕으로 추론됩니다. 이 분류는 결정론적으로 이루어지며 다른 AI 모델을 호출하지 않습니다.

활동 라벨은 확정적인 판단이 아니라 유용한 참고 정보로 활용하세요. 라벨은 전반적인 패턴을 파악하는 데 도움이 되지만, 작업의 전체 맥락을 아는 것은 여러분뿐입니다.

보고서 해석

  • 약 80% 미만의 캐시 적중률이 지속됨: 컨텍스트가 자주 변경되고 있거나 캐싱이 활성화되지 않았을 수 있습니다. 한 번의 이례적인 세션보다 몇 주 동안 지속되는 패턴이 더 중요합니다.
  • 비용이 높은 모델이 여러 소규모 호출을 대부분 처리함: 대규모 모델이 빈번하지만 제한적인 작업을 처리하고 있다는 사실이 보고서에 드러날 수 있습니다. tokentab은 이러한 사용 패턴을 보여 주므로 해당 사용이 의도적인지 확인할 수 있습니다.
  • 채팅 또는 탐색 카테고리가 큼: 기록된 활동의 상당 부분이 편집보다는 논의나 읽기에 해당합니다. 이는 적절할 수도 있지만, 세션이 방향을 잃고 길어졌다는 점을 보여 줄 수도 있습니다.

이러한 패턴은 조사를 시작하기 위한 출발점이지 결론이 아닙니다. 관련 세션에서 실제로 무엇을 하고 있었는지와 보고서를 비교해 보세요.

고급 팁: 다른 공급업체 추가

각 공급업체는 tokentab/providers/ 아래의 모듈로 구현됩니다. 공급업체는 UsageRecord 객체의 평면 목록을 반환하는 collect() 함수를 제공합니다. 공유 레코드 구조는 tokentab/types.py에 정의되어 있습니다.

  1. tokentab/providers/에 공급업체 모듈을 만듭니다.
  2. 공급업체의 로컬 세션 파일을 읽고 파싱합니다.
  3. 관련 사용량 항목을 공통 UsageRecord 형식으로 변환합니다.
  4. collect()에서 레코드를 반환합니다.
  5. tokentab/providers/__init__.py에 공급업체를 추가합니다.

레코드가 공통 형식을 사용하면 기존 가격 계산, 그룹화, CLI 출력 및 대시보드에서 이를 처리할 수 있습니다. README에서는 Claude 파서를 가장 간단한 템플릿으로 사용하고, 추가 예시는 다른 작동하는 파서를 참고할 것을 권장합니다.

실용적인 사용 팁

  • 기본 7일 보고서를 정기적으로 실행하여 최근 변화를 파악하세요.
  • 더 폭넓은 지출 패턴을 검토할 때는 월간 보기를 사용하세요.
  • 특정 코드베이스를 조사하기 전에 프로젝트별로 필터링하세요.
  • tokentab 데이터를 기반으로 스크립트나 사용자 지정 보고서를 만들 때는 JSON을 내보내세요.
  • 모델이 $0.00으로 보고되면 가격 표를 확인하세요.
  • 시각적으로 검토할 때는 대시보드를, 자동화나 공유에는 CLI를 사용하세요.

결론

tokentab은 자격 증명을 요구하거나 컴퓨터 밖으로 데이터를 전송하지 않고도 로컬 Claude Code, Codex 및 Gemini CLI 로그를 실용적인 토큰 및 비용 보고서로 변환합니다. 기본 7일 CLI 보기에서 시작해 기간, 공급업체 및 프로젝트 필터로 결과를 좁힌 다음, 다른 형식이 필요할 때 JSON 또는 localhost 대시보드를 사용하세요. 이 프로젝트는 MIT 라이선스로 제공됩니다.