README.ko.md

여러 플랫폼에서 AI 코딩 어시스턴트의 토큰 사용량과 비용을 추적하는 고성능 CLI 도구 및 시각화 대시보드

Tip

v2 출시 — 네이티브 Rust TUI, 크로스 플랫폼 지원 등.
저는 매주 새로운 오픈소스 프로젝트를 공개합니다. 놓치지 마세요.

	GitHub에서 @junhoyeo를 팔로우하고 더 많은 프로젝트를 만나보세요. AI, 인프라 등 다양한 분야를 다룹니다.

🇺🇸 English | 🇰🇷 한국어 | 🇯🇵 日本語 | 🇨🇳 简体中文

Overview	Models

Daily Summary	Stats

Frontend (3D Contributions Graph)	Wrapped 2025

bunx tokscale submit를 실행하여 사용량 데이터를 리더보드에 제출하고 공개 프로필을 만드세요!

개요

Tokscale은 아래 플랫폼들의 토큰 소비량을 수집하고 분석해 한 눈에 볼 수 있도록 해 줍니다.

로고	클라이언트	데이터 위치	지원 여부
	OpenCode	~/.local/share/opencode/opencode.db (1.2+) 또는 ~/.local/share/opencode/storage/message/	✅ 지원
	Claude Code	~/.claude/projects/	✅ 지원
	OpenClaw	~/.openclaw/agents/ (+ 레거시: .clawdbot, .moltbot, .moldbot)	✅ 지원
	Codex CLI	~/.codex/sessions/	✅ 지원
	Gemini CLI	~/.gemini/tmp/*/chats/*.json	✅ 지원
	Cursor IDE	~/.config/tokscale/cursor-cache/를 통한 API 동기화	✅ 지원
	Amp (AmpCode)	~/.local/share/amp/threads/	✅ 지원
	Droid (Factory Droid)	~/.factory/sessions/	✅ 지원
	Pi	~/.pi/agent/sessions/	✅ 지원
	Kimi CLI	~/.kimi/sessions/	✅ 지원
	Qwen CLI	~/.qwen/projects/	✅ 지원
	Roo Code	~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/tasks/ (+ server: ~/.vscode-server/data/User/globalStorage/rooveterinaryinc.roo-cline/tasks/)	✅ 지원
	Kilo	~/.config/Code/User/globalStorage/kilocode.kilo-code/tasks/ (+ server: ~/.vscode-server/data/User/globalStorage/kilocode.kilo-code/tasks/)	✅ 지원
	Mux	~/.mux/sessions/	✅ 지원
	Kilo CLI	~/.local/share/kilo/kilo.db	✅ 지원
	Crush	$XDG_DATA_HOME/crush/projects.json (프로젝트 레지스트리, 기본값: ~/.local/share/crush/projects.json)	✅ 지원
	Synthetic	hf: 모델/synthetic provider 감지로 다른 소스에서 재귀속 (+ Octofriend: ~/.local/share/octofriend/sqlite.db)	✅ 지원

🚅 LiteLLM의 가격 데이터를 사용해 실시간 비용 계산을 제공합니다. 구간별 가격 모델(대용량 컨텍스트 등)과 캐시 토큰 할인도 지원합니다.

왜 "Tokscale"인가요?

이 프로젝트는 **카르다쇼프 척도(Kardashev Scale)**에서 영감을 받았습니다. 카르다쇼프 척도는 문명의 기술 수준을 에너지 소비량으로 분류합니다. 유형 I 문명은 행성에서 사용 가능한 모든 에너지를 활용하고, 유형 II는 항성의 전체 출력을 포착하며, 유형 III는 은하 전체의 에너지를 통제합니다.

AI 지원 개발 시대에 토큰은 새로운 에너지입니다. 토큰은 우리의 사고력을 구동하고, 생산성을 높이며, 창의적 결과물을 이끌어냅니다. 카르다쇼프 척도가 우주적 규모에서 에너지 소비를 추적하듯, Tokscale은 AI 증강 개발의 단계를 올라가며 토큰 소비를 측정하고 시각화합니다. 가볍게 쓰는 사용자든 매일 수백만 개의 토큰을 소비하는 파워 유저든, Tokscale은 "내가 어디에서 무엇을 얼마나 쓰고 있는지"를 분명하게 보여줍니다.

목차

• 개요
  • 왜 "Tokscale"인가요?
• 기능
• 설치
  • 빠른 시작
  • 사전 요구사항
  • 개발 환경 설정
  • 네이티브 모듈 빌드
• 사용법
  • 기본 명령어
  • TUI 기능
  • 플랫폼별 필터링
  • 날짜 필터링
  • 가격 조회
  • 소셜 플랫폼 명령어
  • Cursor IDE 명령어
  • 예시 출력
  • 설정
  • 환경 변수
• 프론트엔드 시각화
  • 기능
  • 프론트엔드 실행
• 소셜 플랫폼
  • 기능
  • GitHub 프로필 임베드 위젯
  • GitHub 프로필 뱃지
  • 시작하기
  • 데이터 검증
• Wrapped 2025
  • 명령어
  • 포함 내용
• 개발
  • 사전 요구사항
  • 실행 방법
• 지원 플랫폼
  • 네이티브 모듈 타겟
  • Windows 지원
• 세션 데이터 보존
• 데이터 소스
• 가격
• 기여
  • 개발 가이드라인
• 감사의 글
• 라이선스

기능

• 인터랙티브 TUI 모드 - Ratatui 기반의 터미널 UI (기본 모드)
  • 4개 뷰: 개요, 모델, 일별, 통계
  • 키보드 및 마우스 지원
  • 9가지 테마의 GitHub 스타일 기여 그래프
  • 실시간 필터링 및 정렬
  • 깜빡임 없는 렌더링
• 멀티 플랫폼 지원 - OpenCode, Claude Code, Codex CLI, Cursor IDE, Gemini CLI, Amp, Droid, OpenClaw, Pi, Kimi CLI, Qwen CLI, Roo Code, Kilo, Mux, Kilo CLI, Crush, Synthetic 사용량 통합 추적
• 실시간 가격 반영 - LiteLLM에서 최신 가격을 가져와(디스크 캐시 1시간) 비용 계산; OpenRouter 자동 폴백 및 신규 모델용 Cursor 가격 지원
• 상세 분석 - 입력, 출력, 캐시 읽기/쓰기, 추론 토큰까지 추적
• 네이티브 Rust 코어 - 모든 파싱과 집계를 Rust로 처리해 최대 10배 빠른 성능
• 웹 시각화 - 2D 및 3D 뷰의 인터랙티브 기여 그래프
• 유연한 필터링 - 플랫폼, 날짜 범위 또는 연도별 필터링
• JSON 내보내기 - 외부 시각화 도구/자동화용 데이터 생성
• 소셜 플랫폼 - 사용량 공유, 리더보드 경쟁, 공개 프로필 조회

설치

빠른 시작

# npx로 바로 실행
npx tokscale@latest

# 또는 bunx 사용
bunx tokscale@latest

# 라이트 모드 (테이블 렌더링만)
npx tokscale@latest --light

이게 전부입니다! 별도 설정 없이 바로 완전한 인터랙티브 TUI 경험을 제공합니다.

패키지 구조: tokscale은 @tokscale/cli를 설치하는 별칭 패키지입니다 (swc처럼). 둘 다 네이티브 Rust 코어 (@tokscale/core)가 포함된 동일한 CLI를 설치합니다.

사전 요구사항

• Node.js 또는 Bun
• (선택) 소스에서 네이티브 모듈을 빌드하려면 Rust 툴체인

개발 환경 설정

로컬 개발 또는 소스에서 빌드하는 경우:

# 저장소 클론
git clone https://github.com/junhoyeo/tokscale.git
cd tokscale

# Bun 설치 (아직 설치하지 않은 경우)
curl -fsSL https://bun.sh/install | bash

# 의존성 설치
bun install

# 개발 모드에서 CLI 실행
bun run cli

참고: bun run cli는 로컬 개발용입니다. bunx tokscale로 설치하면 명령이 직접 실행됩니다. 아래 사용법 섹션은 설치된 바이너리 명령을 보여줍니다.

네이티브 모듈 빌드

네이티브 Rust 모듈은 CLI 동작에 필수입니다. 병렬 파일 스캐닝과 SIMD JSON 파싱을 통해 처리 속도를 약 10배 향상시킵니다:

# 네이티브 코어 빌드 (저장소 루트에서 실행)
bun run build:core

참고: bunx tokscale@latest로 설치하면 네이티브 바이너리가 사전 빌드되어 포함됩니다. 소스에서 빌드는 로컬 개발 시에만 필요합니다.

사용법

기본 명령어

# 인터랙티브 TUI 실행 (기본)
tokscale

# 특정 탭으로 TUI 실행
tokscale models    # 모델 탭
tokscale monthly   # 일별 뷰 (일별 분석 표시)

# 레거시 CLI 테이블 출력 사용
tokscale --light
tokscale models --light

# 명시적으로 TUI 실행
tokscale tui

# 기여 그래프 데이터를 JSON으로 내보내기
tokscale graph --output data.json

# JSON으로 데이터 출력 (스크립팅/자동화용)
tokscale --json                    # 기본 모델 뷰를 JSON으로
tokscale models --json             # 모델 분석을 JSON으로
tokscale monthly --json            # 월별 분석을 JSON으로
tokscale models --json > report.json   # 파일로 저장

TUI 기능

인터랙티브 TUI 모드는 다음을 제공합니다:

• 4개 뷰: 개요 (차트 + 상위 모델), 모델, 일별, 통계 (기여 그래프)
• 키보드 내비게이션:
  • 1-4 또는 ←/→/Tab: 뷰 전환
  • ↑/↓: 목록 탐색
  • c/d/t: 비용/날짜/토큰별 정렬
  • s: 소스 선택 다이얼로그 열기
  • g: 그룹 기준 선택 다이얼로그 열기 (모델, 클라이언트+모델, 클라이언트+프로바이더+모델)
  • p: 9가지 색상 테마 순환
  • r: 데이터 새로고침
  • e: JSON으로 내보내기
  • q: 종료
• 마우스 지원: 탭, 버튼, 필터 클릭
• 테마: Green, Halloween, Teal, Blue, Pink, Purple, Orange, Monochrome, YlGnBu
• 설정 저장: 설정이 ~/.config/tokscale/settings.json에 저장됨 (설정 참조)

그룹 기준 전략

TUI에서 g를 누르거나 --light/--json 모드에서 --group-by를 사용하여 모델 행 집계 방식을 제어합니다:

전략	플래그	TUI 기본값	효과
모델	--group-by model	✅	모델당 한 행 — 모든 클라이언트와 프로바이더 병합
클라이언트 + 모델	--group-by client,model		클라이언트-모델 쌍당 한 행
클라이언트 + 프로바이더 + 모델	--group-by client,provider,model		가장 세분화 — 병합 없음

--group-by model (가장 통합)

클라이언트	프로바이더	모델	비용
OpenCode, Claude, Amp	github-copilot, anthropic	claude-opus-4-5	$2,424
OpenCode, Claude	anthropic, github-copilot	claude-sonnet-4-5	$1,332

--group-by client,model (CLI 기본값)

클라이언트	프로바이더	모델	비용
OpenCode	github-copilot, anthropic	claude-opus-4-5	$1,368
Claude	anthropic	claude-opus-4-5	$970

--group-by client,provider,model (가장 세분화)

클라이언트	프로바이더	모델	비용
OpenCode	github-copilot	claude-opus-4-5	$1,200
OpenCode	anthropic	claude-opus-4-5	$168
Claude	anthropic	claude-opus-4-5	$970

플랫폼별 필터링

# OpenCode 사용량만 표시
tokscale --opencode

# Claude Code 사용량만 표시
tokscale --claude

# Codex CLI 사용량만 표시
tokscale --codex

# Gemini CLI 사용량만 표시
tokscale --gemini

# Cursor IDE 사용량만 표시 (먼저 `tokscale cursor login` 필요)
tokscale --cursor

# Kimi CLI 사용량만 표시
tokscale --kimi

# Qwen CLI 사용량만 표시
tokscale --qwen

# Amp 사용량만 표시
tokscale --amp

# Droid 사용량만 표시
tokscale --droid

# OpenClaw 사용량만 표시
tokscale --openclaw

# Pi 사용량만 표시
tokscale --pi

# Roo Code 사용량만 표시
tokscale --roocode

# Kilo 사용량만 표시
tokscale --kilocode

# Mux 사용량만 표시
tokscale --mux

# Kilo CLI 사용량만 표시
tokscale --kilo

# Crush 사용량만 표시
tokscale --crush

# Synthetic (synthetic.new) 사용량만 표시
tokscale --synthetic

# 필터 조합
tokscale --opencode --claude

날짜 필터링

날짜 필터는 리포트를 생성하는 모든 명령어에서 작동합니다 (tokscale, tokscale models, tokscale monthly, tokscale graph):

# 빠른 날짜 단축키
tokscale --today              # 오늘만
tokscale --week               # 최근 7일
tokscale --month              # 이번 달

# 사용자 정의 날짜 범위 (포함, 로컬 타임존)
tokscale --since 2024-01-01 --until 2024-12-31

# 연도별 필터
tokscale --year 2024

# 다른 옵션과 조합
tokscale models --week --claude --json
tokscale monthly --month --benchmark

참고: 날짜 필터는 로컬 타임존을 사용합니다. --since와 --until 모두 해당 날짜를 포함합니다.

가격 조회

모든 모델의 실시간 가격을 조회합니다:

# 모델 가격 조회
tokscale pricing "claude-3-5-sonnet-20241022"
tokscale pricing "gpt-4o"
tokscale pricing "grok-code"

# 특정 프로바이더 소스 강제 지정
tokscale pricing "grok-code" --provider openrouter
tokscale pricing "claude-3-5-sonnet" --provider litellm

조회 전략:

가격 조회는 다단계 해석 전략을 사용합니다:

1. 정확한 일치 - LiteLLM/OpenRouter 데이터베이스에서 직접 조회
2. 별칭 해석 - 친숙한 이름 해석 (예: big-pickle → glm-4.7)
3. 티어 접미사 제거 - 품질 티어 제거 (gpt-5.2-xhigh → gpt-5.2)
4. 버전 정규화 - 버전 형식 처리 (claude-3-5-sonnet ↔ claude-3.5-sonnet)
5. 프로바이더 접두사 매칭 - 일반 접두사 시도 (anthropic/, openai/ 등)
6. Cursor 모델 가격 - LiteLLM/OpenRouter에 아직 없는 모델의 하드코딩 가격 (예: gpt-5.3-codex)
7. 퍼지 매칭 - 부분 모델 이름에 대한 단어 경계 매칭

프로바이더 우선순위:

여러 일치 항목이 있을 때 원본 모델 제작사가 리셀러보다 우선됩니다:

우선 (원본)	후순위 (리셀러)
xai/ (Grok)	azure_ai/
anthropic/ (Claude)	bedrock/
openai/ (GPT)	vertex_ai/
google/ (Gemini)	together_ai/
meta-llama/	fireworks_ai/

예시: grok-code는 azure_ai/grok-code-fast-1 ($3.50/$17.50) 대신 xai/grok-code-fast-1 ($0.20/$1.50)와 일치합니다.

소셜 플랫폼 명령어

# Tokscale 로그인 (GitHub 인증을 위해 브라우저 열기)
tokscale login

# 로그인한 사용자 확인
tokscale whoami

# 사용량 데이터를 리더보드에 제출
tokscale submit

# 필터와 함께 제출
tokscale submit --opencode --claude --since 2024-01-01

# 제출될 내용 미리보기 (드라이 런)
tokscale submit --dry-run

# 로그아웃
tokscale logout

Cursor IDE 명령어

Cursor IDE는 세션 토큰을 통한 별도의 인증이 필요합니다 (소셜 플랫폼 로그인과 다름):

# Cursor 로그인 (브라우저에서 세션 토큰 필요)
# --name은 선택이며, 나중에 계정을 구분하기 위한 라벨입니다
tokscale cursor login --name work

# Cursor 인증 상태 및 세션 유효성 확인
tokscale cursor status

# 저장된 Cursor 계정 목록
tokscale cursor accounts

# 활성 계정 전환 (cursor-cache/usage.csv에 동기화되는 계정)
tokscale cursor switch work

# 특정 계정 로그아웃 (기록은 보관, 합산에서는 제외)
tokscale cursor logout --name work

# 로그아웃 + 해당 계정 캐시 삭제
tokscale cursor logout --name work --purge-cache

# 모든 Cursor 계정 로그아웃 (기록은 보관, 합산에서는 제외)
tokscale cursor logout --all

# 모든 계정 로그아웃 + 캐시 삭제
tokscale cursor logout --all --purge-cache

자격 증명 저장: Cursor 계정들은 ~/.config/tokscale/cursor-credentials.json에 저장됩니다. 사용량 데이터는 ~/.config/tokscale/cursor-cache/에 캐시됩니다 (활성 계정은 usage.csv, 추가 계정은 usage.<account>.csv).

기본적으로 tokscale은 저장된 모든 Cursor 계정의 사용량을 합산합니다 (cursor-cache/usage*.csv 전체). 호환성을 위해 활성 계정은 cursor-cache/usage.csv에 동기화됩니다.

로그아웃 시에는 캐시된 사용량 기록을 cursor-cache/archive/로 옮겨 보관하며(그래서 합산에서는 제외됨), 완전 삭제를 원하면 --purge-cache를 사용하세요.

Cursor 세션 토큰 얻는 방법:

1. 브라우저에서 https://www.cursor.com/settings 열기
2. 개발자 도구 열기 (F12)
3. 옵션 A - Network 탭: 페이지에서 아무 동작을 하고, cursor.com/api/*에 대한 요청을 찾아, Request Headers에서 Cookie 헤더를 확인하고, WorkosCursorSessionToken= 뒤의 값만 복사
4. 옵션 B - Application 탭: Application → Cookies → https://www.cursor.com으로 이동, WorkosCursorSessionToken 쿠키를 찾아 값 복사 (쿠키 이름이 아닌 값)

⚠️ 보안 경고: 세션 토큰을 비밀번호처럼 취급하세요. 절대 공개적으로 공유하거나 버전 관리에 커밋하지 마세요. 토큰은 Cursor 계정에 대한 전체 액세스 권한을 부여합니다.

예시 출력 (--light 버전)

설정

Tokscale은 설정을 ~/.config/tokscale/settings.json에 저장합니다:

{
  "colorPalette": "blue",
  "includeUnusedModels": false
}

설정	타입	기본값	설명
colorPalette	string	"blue"	TUI 색상 테마 (green, halloween, teal, blue, pink, purple, orange, monochrome, ylgnbu)
includeUnusedModels	boolean	false	리포트에서 제로 토큰 모델 표시
autoRefreshEnabled	boolean	false	TUI 자동 새로고침 활성화
autoRefreshMs	number	60000	자동 새로고침 간격 (30000-3600000ms)
nativeTimeoutMs	number	300000	네이티브 서브프로세스 처리 최대 시간 (5000-3600000ms)

환경 변수

환경 변수는 설정 파일 값을 오버라이드합니다. CI/CD 또는 일회성 사용:

변수	기본값	설명
TOKSCALE_NATIVE_TIMEOUT_MS	300000 (5분)	nativeTimeoutMs 설정 오버라이드

# 예시: 매우 큰 데이터셋에 대한 타임아웃 증가
TOKSCALE_NATIVE_TIMEOUT_MS=600000 tokscale graph --output data.json

참고: 영구적인 변경은 ~/.config/tokscale/settings.json에서 nativeTimeoutMs를 설정하는 것을 권장합니다. 환경 변수는 일회성 오버라이드나 CI/CD에 적합합니다.

Headless 모드

Tokscale은 자동화, CI/CD 파이프라인 및 배치 처리를 위한 Codex CLI headless 출력의 토큰 사용량을 집계할 수 있습니다.

Headless 모드란?

Codex CLI를 JSON 출력 플래그와 함께 실행할 때(예: `codex exec --json`), 일반 세션 디렉토리에 저장하는 대신 사용량 데이터를 stdout으로 출력합니다. Headless 모드를 사용하면 이러한 사용량을 캡처하고 추적할 수 있습니다.

저장 위치: `~/.config/tokscale/headless/`

macOS에서는 `TOKSCALE_HEADLESS_DIR`이 설정되지 않은 경우 Tokscale이 `~/Library/Application Support/tokscale/headless/`도 스캔합니다.

Tokscale은 다음 디렉토리 구조를 자동으로 스캔합니다: ``` ~/.config/tokscale/headless/ └── codex/ # Codex CLI JSONL 출력 ```

환경 변수: `TOKSCALE_HEADLESS_DIR`을 설정하여 headless 로그 디렉토리를 커스터마이징할 수 있습니다: ```bash export TOKSCALE_HEADLESS_DIR="$HOME/my-custom-logs" ```

권장 (자동 캡처):

도구	명령어 예시
Codex CLI	`tokscale headless codex exec -m gpt-5 "implement feature"`

수동 리다이렉트 (선택사항):

도구	명령어 예시
Codex CLI	`codex exec --json "implement feature" > ~/.config/tokscale/headless/codex/ci-run.jsonl`

진단:

```bash

스캔 위치 및 headless 카운트 표시

tokscale sources tokscale sources --json ```

CI/CD 통합 예시:

```bash

GitHub Actions 워크플로우에서

• name: Run AI automation run: | mkdir -p ~/.config/tokscale/headless/codex codex exec --json "review code changes" \ > ~/.config/tokscale/headless/codex/pr-${{ github.event.pull_request.number }}.jsonl

나중에 사용량 추적

• name: Report token usage run: tokscale --json ```

참고: Headless 캡처는 Codex CLI만 지원됩니다. Codex를 직접 실행하는 경우 위와 같이 stdout을 headless 디렉토리로 리다이렉트해야 합니다.

프론트엔드 시각화

프론트엔드는 GitHub 스타일의 기여 그래프 시각화를 제공합니다:

기능

• 2D 뷰: 클래식 GitHub 기여 캘린더
• 3D 뷰: 토큰 사용량에 따른 높이의 아이소메트릭 3D 기여 그래프
• 다양한 색상 팔레트: GitHub, GitLab, Halloween, Winter 등
• 3가지 테마 토글: Light / Dark / System (OS 설정 따름)
• GitHub Primer 디자인: GitHub의 공식 색상 시스템 사용
• 인터랙티브 툴팁: 호버 시 상세 일별 분석 표시
• 일별 분석 패널: 클릭하여 소스별, 모델별 세부사항 확인
• 연도 필터링: 연도 간 탐색
• 소스 필터링: 플랫폼별 필터 (OpenCode, Claude, Codex, Cursor, Gemini, Amp, Droid, OpenClaw, Pi, Kimi, Qwen, Roo Code, Kilo, Mux, Kilo CLI, Crush, Synthetic)
• 통계 패널: 총 비용, 토큰, 활동 일수, 연속 기록
• FOUC 방지: React 하이드레이션 전 테마 적용 (깜빡임 없음)

프론트엔드 실행

cd packages/frontend
bun install
bun run dev

http://localhost:3000을 열어 소셜 플랫폼에 접근하세요.

소셜 플랫폼

Tokscale은 사용량 데이터를 공유하고 다른 개발자와 경쟁할 수 있는 소셜 플랫폼을 포함합니다.

기능

• 리더보드 - 모든 플랫폼에서 가장 많은 토큰을 사용하는 사람 확인
• 사용자 프로필 - 기여 그래프와 통계가 있는 공개 프로필
• 기간 필터링 - 전체 기간, 이번 달, 이번 주 통계 조회
• GitHub 통합 - GitHub 계정으로 로그인
• 로컬 뷰어 - 제출하지 않고 비공개로 데이터 조회

GitHub 프로필 임베드 위젯

GitHub 프로필 README에 Tokscale 공개 통계를 직접 임베드할 수 있습니다:

[![Tokscale Stats](https://tokscale.ai/api/embed/<username>/svg)](https://tokscale.ai/u/<username>)

• <username>을 GitHub 사용자명으로 교체하세요
• 선택적 쿼리 파라미터:
  • theme=light 라이트 테마 사용
  • sort=tokens (기본값) 또는 sort=cost 랭킹 기준 제어
  • compact=1 컴팩트 레이아웃 + 축약 숫자 표기법 사용 (예: 1.2M, $3.4K)
• 예시:
  • https://tokscale.ai/api/embed/<username>/svg?theme=light&sort=cost&compact=1

GitHub 프로필 뱃지

shields.io 스타일의 더 간결한 뱃지를 사용할 수도 있습니다:

![Tokscale Tokens](https://tokscale.ai/api/badge/<username>/svg)

• <username>을 GitHub 사용자명으로 교체하세요
• 선택적 쿼리 파라미터:
  • metric=tokens (기본값), metric=cost, 또는 metric=rank
  • style=flat (기본값) 또는 style=flat-square
  • sort=tokens (기본값) 또는 sort=cost 랭킹 기준 제어
  • compact=1 간결한 숫자 표기 사용 (예: 1.2M, $3.4K)
  • label=<텍스트> 왼쪽 라벨 커스텀
  • color=<hex> 오른쪽 배경색 커스텀 (예: color=ff5733)
• 예시:
  • https://tokscale.ai/api/badge/<username>/svg?metric=cost&compact=1
  • https://tokscale.ai/api/badge/<username>/svg?metric=rank&sort=cost&style=flat-square

시작하기

1. 로그인 - tokscale login을 실행하여 GitHub로 인증
2. 제출 - tokscale submit을 실행하여 사용량 데이터 업로드
3. 조회 - 웹 플랫폼을 방문하여 프로필과 리더보드 확인

데이터 검증

제출된 데이터는 레벨 1 검증을 거칩니다:

• 수학적 일관성 (합계 일치, 음수 없음)
• 미래 날짜 없음
• 필수 필드 존재
• 중복 감지

Wrapped 2025

Spotify Wrapped에서 영감을 받아, AI 코딩 어시스턴트 사용량을 요약한 아름다운 연간 리뷰 이미지를 생성합니다.

bunx tokscale@latest wrapped	bunx tokscale@latest wrapped --clients	bunx tokscale@latest wrapped --agents --disable-pinned

명령어

# 현재 연도의 Wrapped 이미지 생성
tokscale wrapped

# 특정 연도의 Wrapped 이미지 생성
tokscale wrapped --year 2025

포함 내용

생성된 이미지에는 다음이 포함됩니다:

• 총 토큰 - 해당 연도의 총 토큰 소비량
• 상위 모델 - 비용 기준 상위 3개 AI 모델
• 상위 클라이언트 - 가장 많이 사용한 3개 플랫폼 (OpenCode, Claude Code, Cursor 등)
• 메시지 - 총 AI 인터랙션 수
• 활동 일수 - 최소 1회 이상 AI 인터랙션이 있었던 일수
• 비용 - LiteLLM 가격 기준 추정 총비용
• 연속 기록 - 가장 긴 연속 활동 일수
• 기여 그래프 - 연간 활동을 보여주는 히트맵

생성된 PNG는 소셜 미디어 공유에 최적화되어 있습니다. 커뮤니티와 함께 코딩 여정을 공유하세요!

개발

빠른 설정: 빠르게 시작하려면 위 설치 섹션의 개발 환경 설정을 참조하세요.

사전 요구사항

# Bun (필수)
bun --version

# Rust (네이티브 모듈용)
rustc --version
cargo --version

실행 방법

개발 환경 설정을 따른 후:

# 네이티브 모듈 빌드 (선택사항이지만 권장)
bun run build:core

# 개발 모드로 실행 (TUI 실행)
cd packages/cli && bun src/cli.ts

# 또는 레거시 CLI 모드 사용
cd packages/cli && bun src/cli.ts --light

고급 개발

프로젝트 스크립트

스크립트	설명
bun run cli	개발 모드에서 CLI 실행 (Bun으로 TUI)
bun run build:core	네이티브 Rust 모듈 빌드 (릴리스)
bun run build:cli	CLI TypeScript를 dist/로 빌드
bun run build	core와 CLI 모두 빌드
bun run dev:frontend	프론트엔드 개발 서버 실행

패키지별 스크립트 (패키지 디렉토리 내에서):

• packages/cli: bun run dev, bun run tui
• packages/core: bun run build:debug, bun run test, bun run bench

참고: 이 프로젝트는 개발 시 Bun을 패키지 매니저로 사용합니다.

테스트

# 네이티브 모듈 테스트 (Rust)
cd packages/core
bun run test:rust      # Cargo 테스트
bun run test           # Node.js 통합 테스트
bun run test:all       # 둘 다

네이티브 모듈 개발

cd packages/core

# 디버그 모드로 빌드 (빠른 컴파일)
bun run build:debug

# 릴리스 모드로 빌드 (최적화됨)
bun run build

# Rust 벤치마크 실행
bun run bench

그래프 명령어 옵션

# 그래프 데이터를 파일로 내보내기
tokscale graph --output usage-data.json

# 날짜 필터링 (모든 단축키 사용 가능)
tokscale graph --today
tokscale graph --week
tokscale graph --since 2024-01-01 --until 2024-12-31
tokscale graph --year 2024

# 플랫폼별 필터
tokscale graph --opencode --claude

# 처리 시간 벤치마크 표시
tokscale graph --output data.json --benchmark

벤치마크 플래그

성능 분석을 위한 처리 시간 표시:

tokscale --benchmark           # 기본 뷰와 함께 처리 시간 표시
tokscale models --benchmark    # 모델 리포트 벤치마크
tokscale monthly --benchmark   # 월별 리포트 벤치마크
tokscale graph --benchmark     # 그래프 생성 벤치마크

프론트엔드용 데이터 생성

# 시각화용 데이터 내보내기
tokscale graph --output packages/frontend/public/my-data.json

성능

네이티브 Rust 모듈은 상당한 성능 향상을 제공합니다:

작업	TypeScript	Rust 네이티브	속도 향상
파일 탐색	~500ms	~50ms	10배
JSON 파싱	~800ms	~100ms	8배
집계	~200ms	~25ms	8배
총합	~1.5초	~175ms	~8.5배

약 1000개의 세션 파일, 100k 메시지 기준 벤치마크

메모리 최적화

네이티브 모듈은 다음을 통해 약 45% 메모리 절감도 제공합니다:

• 스트리밍 JSON 파싱 (전체 파일 버퍼링 없음)
• 제로 카피 문자열 처리
• 맵-리듀스를 통한 효율적인 병렬 집계

벤치마크 실행

# 합성 데이터 생성
cd packages/benchmarks && bun run generate

# Rust 벤치마크 실행
cd packages/core && bun run bench

지원 플랫폼

네이티브 모듈 대상

플랫폼	아키텍처	상태
macOS	x86_64	✅ 지원
macOS	aarch64 (Apple Silicon)	✅ 지원
Linux	x86_64 (glibc)	✅ 지원
Linux	aarch64 (glibc)	✅ 지원
Linux	x86_64 (musl)	✅ 지원
Linux	aarch64 (musl)	✅ 지원
Windows	x86_64	✅ 지원
Windows	aarch64	✅ 지원

Windows 지원

Tokscale은 Windows를 완벽하게 지원합니다. TUI와 CLI는 macOS/Linux와 동일하게 작동합니다.

Windows 설치:

# Bun 설치 (PowerShell)
powershell -c "irm bun.sh/install.ps1 | iex"

# tokscale 실행
bunx tokscale@latest

Windows에서의 데이터 위치

AI 코딩 도구들은 크로스 플랫폼 위치에 세션 데이터를 저장합니다. 대부분의 도구는 모든 플랫폼에서 동일한 상대 경로를 사용합니다:

도구	Unix 경로	Windows 경로	출처
OpenCode	~/.local/share/opencode/	%USERPROFILE%\.local\share\opencode\	크로스 플랫폼 일관성을 위해 xdg-basedir 사용 (소스)
Claude Code	~/.claude/	%USERPROFILE%\.claude\	모든 플랫폼에서 동일한 경로
OpenClaw	~/.openclaw/ (+ 레거시: .clawdbot, .moltbot, .moldbot)	%USERPROFILE%\.openclaw\ (+ 레거시 경로)	모든 플랫폼에서 동일한 경로
Codex CLI	~/.codex/	%USERPROFILE%\.codex\	CODEX_HOME 환경변수로 설정 가능 (소스)
Gemini CLI	~/.gemini/	%USERPROFILE%\.gemini\	모든 플랫폼에서 동일한 경로
Amp	~/.local/share/amp/	%USERPROFILE%\.local\share\amp\	OpenCode와 동일하게 xdg-basedir 사용
Cursor	API 동기화	API 동기화	API를 통해 데이터 가져오기, %USERPROFILE%\.config\tokscale\cursor-cache\에 캐시
Droid	~/.factory/	%USERPROFILE%\.factory\	모든 플랫폼에서 동일한 경로
Pi	~/.pi/	%USERPROFILE%\.pi\	모든 플랫폼에서 동일한 경로
Kimi CLI	~/.kimi/	%USERPROFILE%\.kimi\	모든 플랫폼에서 동일한 경로
Qwen CLI	~/.qwen/	%USERPROFILE%\.qwen\	모든 플랫폼에서 동일한 경로
Roo Code	~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/tasks/	%USERPROFILE%\.config\Code\User\globalStorage\rooveterinaryinc.roo-cline\tasks\	VS Code globalStorage 작업 로그
Kilo	~/.config/Code/User/globalStorage/kilocode.kilo-code/tasks/	%USERPROFILE%\.config\Code\User\globalStorage\kilocode.kilo-code\tasks\	VS Code globalStorage 작업 로그
Mux	~/.mux/sessions/	%USERPROFILE%\.mux\sessions\	모든 플랫폼에서 동일한 경로
Kilo CLI	~/.local/share/kilo/	%USERPROFILE%\.local\share\kilo\	OpenCode와 같이 xdg-basedir 사용
Crush	$XDG_DATA_HOME/crush/ (기본값: ~/.local/share/crush/)	%USERPROFILE%\.local\share\crush\ (설정된 경우 %XDG_DATA_HOME%\crush\)	기본 경로를 포함한 XDG 데이터 디렉토리 사용
Synthetic	다른 소스에서 재귀속	다른 소스에서 재귀속	hf: 모델 접두사 + synthetic provider 감지

참고: Windows에서 ~는 %USERPROFILE%로 확장됩니다 (예: C:\Users\사용자이름). 이러한 도구들은 %APPDATA%와 같은 Windows 기본 경로 대신 크로스 플랫폼 일관성을 위해 의도적으로 Unix 스타일 경로(.local/share 등)를 사용합니다.

Windows 전용 설정

Tokscale은 다음 위치에 설정을 저장합니다:

• 설정: %USERPROFILE%\.config\tokscale\settings.json
• 캐시: %USERPROFILE%\.cache\tokscale\
• Cursor 자격 증명: %USERPROFILE%\.config\tokscale\cursor-credentials.json

세션 데이터 보존

기본적으로 일부 AI 코딩 어시스턴트는 오래된 세션 파일을 자동으로 삭제합니다. 정확한 추적을 위해 사용 기록을 보존하려면 정리 기간을 비활성화하거나 연장하세요.

플랫폼	기본값	설정 파일	비활성화 설정	출처
Claude Code	⚠️ 30일	~/.claude/settings.json	"cleanupPeriodDays": 9999999999	문서
Gemini CLI	비활성화됨	~/.gemini/settings.json	"general.sessionRetention.enabled": false	문서
Codex CLI	비활성화됨	N/A	정리 기능 없음	#6015
OpenCode	비활성화됨	N/A	정리 기능 없음	#4980

Claude Code

기본값: 30일 정리 기간

~/.claude/settings.json에 추가:

{
  "cleanupPeriodDays": 9999999999
}

매우 큰 값 (예: 9999999999일 ≈ 2700만 년)을 설정하면 사실상 정리가 비활성화됩니다.

Gemini CLI

기본값: 정리 비활성화됨 (세션이 영구 보존)

정리를 활성화했다가 비활성화하려면 ~/.gemini/settings.json에서 제거하거나 enabled: false로 설정:

{
  "general": {
    "sessionRetention": {
      "enabled": false
    }
  }
}

또는 매우 긴 보존 기간 설정:

{
  "general": {
    "sessionRetention": {
      "enabled": true,
      "maxAge": "9999999d"
    }
  }
}

Codex CLI

기본값: 자동 정리 없음 (세션이 영구 보존)

Codex CLI는 내장 세션 정리가 없습니다. ~/.codex/sessions/의 세션은 무기한 유지됩니다.

참고: 이에 대한 기능 요청이 있습니다: #6015

OpenCode

기본값: 자동 정리 없음 (세션이 영구 보존)

OpenCode는 내장 세션 정리가 없습니다. ~/.local/share/opencode/storage/의 세션은 무기한 유지됩니다.

참고: #4980 참조

---

데이터 소스

OpenCode

위치: ~/.local/share/opencode/opencode.db (v1.2+) 또는 storage/message/{sessionId}/*.json (레거시)

OpenCode 1.2+는 세션을 SQLite에 저장합니다. Tokscale은 SQLite를 먼저 읽고, 이전 버전의 경우 레거시 JSON 파일로 폴백합니다.

각 메시지 포함 내용:

{
  "id": "msg_xxx",
  "role": "assistant",
  "modelID": "claude-sonnet-4-20250514",
  "providerID": "anthropic",
  "tokens": {
    "input": 1234,
    "output": 567,
    "reasoning": 0,
    "cache": { "read": 890, "write": 123 }
  },
  "time": { "created": 1699999999999 }
}

Claude Code

위치: ~/.claude/projects/{projectPath}/*.jsonl

어시스턴트 메시지의 사용량 데이터를 포함하는 JSONL 형식:

{"type": "assistant", "message": {"model": "claude-sonnet-4-20250514", "usage": {"input_tokens": 1234, "output_tokens": 567, "cache_read_input_tokens": 890}}, "timestamp": "2024-01-01T00:00:00Z"}

Codex CLI

위치: ~/.codex/sessions/*.jsonl

token_count 이벤트가 있는 이벤트 기반 형식:

{"type": "event_msg", "payload": {"type": "token_count", "info": {"last_token_usage": {"input_tokens": 1234, "output_tokens": 567}}}}

Gemini CLI

위치: ~/.gemini/tmp/{projectHash}/chats/*.json

메시지 배열을 포함한 세션 파일:

{
  "sessionId": "xxx",
  "messages": [
    {"type": "gemini", "model": "gemini-2.5-pro", "tokens": {"input": 1234, "output": 567, "cached": 890, "thoughts": 123}}
  ]
}

Cursor IDE

위치: ~/.config/tokscale/cursor-cache/ (Cursor API를 통해 동기화)

Cursor 데이터는 세션 토큰을 사용하여 Cursor API에서 가져와 로컬에 캐시됩니다. 인증하려면 tokscale cursor login을 실행하세요. 설정 안내는 Cursor IDE 명령어를 참조하세요.

OpenClaw

위치: ~/.openclaw/agents/*/sessions/sessions.json (레거시 경로도 스캔: ~/.clawdbot/, ~/.moltbot/, ~/.moldbot/)

JSONL 세션 파일을 가리키는 인덱스 파일:

{
  "agent:main:main": {
    "sessionId": "uuid",
    "sessionFile": "/path/to/session.jsonl"
  }
}

model_change 이벤트와 어시스턴트 메시지가 포함된 세션 JSONL 형식:

{"type":"model_change","provider":"openai-codex","modelId":"gpt-5.2"}
{"type":"message","message":{"role":"assistant","usage":{"input":1660,"output":55,"cacheRead":108928,"cost":{"total":0.02}},"timestamp":1769753935279}}

Pi

위치: ~/.pi/agent/sessions/<encoded-cwd>/*.jsonl

세션 헤더와 메시지 항목을 포함하는 JSONL 형식:

{"type":"session","id":"pi_ses_001","timestamp":"2026-01-01T00:00:00.000Z","cwd":"/tmp"}
{"type":"message","id":"msg_001","timestamp":"2026-01-01T00:00:01.000Z","message":{"role":"assistant","model":"claude-3-5-sonnet","provider":"anthropic","usage":{"input":100,"output":50,"cacheRead":10,"cacheWrite":5,"totalTokens":165}}}

Kimi CLI

위치: ~/.kimi/sessions/{GROUP_ID}/{SESSION_UUID}/wire.jsonl

StatusUpdate 메시지를 포함하는 wire.jsonl 형식:

{"type": "metadata", "protocol_version": "1.3"}
{"timestamp": 1770983426.420942, "message": {"type": "StatusUpdate", "payload": {"token_usage": {"input_other": 1562, "output": 2463, "input_cache_read": 0, "input_cache_creation": 0}, "message_id": "chatcmpl-xxx"}}}

Qwen CLI

위치: ~/.qwen/projects/{PROJECT_PATH}/chats/{CHAT_ID}.jsonl

형식: JSONL — 줄당 하나의 JSON 객체, 각각 type, model, timestamp, sessionId, usageMetadata 필드 포함.

토큰 필드 (usageMetadata에서):

• promptTokenCount → 입력 토큰
• candidatesTokenCount → 출력 토큰
• thoughtsTokenCount → 추론/사고 토큰
• cachedContentTokenCount → 캐시된 입력 토큰

Roo Code

위치:

• 로컬: ~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/tasks/{TASK_ID}/ui_messages.json
• 서버 (최선 노력): ~/.vscode-server/data/User/globalStorage/rooveterinaryinc.roo-cline/tasks/{TASK_ID}/ui_messages.json

각 작업 디렉토리에는 모델/에이전트 메타데이터에 사용되는 <environment_details> 블록이 포함된 api_conversation_history.json이 포함될 수 있습니다.

ui_messages.json은 UI 이벤트 배열입니다. Tokscale은 다음만 계산합니다:

• type == "say"
• say == "api_req_started"

text 필드는 토큰/비용 메타데이터를 포함하는 JSON입니다:

{
  "type": "say",
  "say": "api_req_started",
  "ts": "2026-02-18T12:00:00Z",
  "text": "{\"cost\":0.12,\"tokensIn\":100,\"tokensOut\":50,\"cacheReads\":20,\"cacheWrites\":5,\"apiProtocol\":\"anthropic\"}"
}

Kilo

위치:

• 로컬: ~/.config/Code/User/globalStorage/kilocode.kilo-code/tasks/{TASK_ID}/ui_messages.json
• 서버 (최선 노력): ~/.vscode-server/data/User/globalStorage/kilocode.kilo-code/tasks/{TASK_ID}/ui_messages.json

Kilo는 Roo Code와 동일한 작업 로그 형식을 사용합니다. Tokscale은 동일한 규칙을 적용합니다:

• ui_messages.json에서 say/api_req_started 이벤트만 계산
• text JSON에서 tokensIn, tokensOut, cacheReads, cacheWrites, cost, apiProtocol 파싱
• 사용 가능한 경우 인접한 api_conversation_history.json에서 모델/에이전트 메타데이터 보강

Mux

위치: ~/.mux/sessions/{WORKSPACE_ID}/session-usage.json

Mux는 세션별 누적 토큰 사용량을 session-usage.json 파일에 저장합니다. 각 파일에는 모델별 토큰 분류가 포함된 byModel 맵이 있습니다: input, cached (캐시 읽기), cacheCreate (캐시 쓰기), output, reasoning 모델명은 provider:model 형식을 사용합니다 (예: anthropic:claude-opus-4-6) — tokscale은 모델 식별을 위해 provider 접두사를 제거합니다 하위 에이전트 사용량은 Mux에 의해 자동으로 상위 세션에 합산되므로 중복 집계가 없습니다

Kilo CLI

위치: ~/.local/share/kilo/kilo.db

Kilo CLI는 OpenCode와 유사한 SQLite 데이터베이스에 세션 데이터를 저장합니다. 각 메시지 행에는 모델 및 공급자 속성과 함께 메시지별 토큰 분류(입력, 출력, 캐시 읽기/쓰기, 추론)가 포함됩니다.

Crush

위치: $XDG_DATA_HOME/crush/projects.json를 통해 발견되는 프로젝트별 SQLite 데이터베이스 (기본값: ~/.local/share/crush/projects.json)

Crush는 프로젝트별 SQLite 데이터베이스(crush.db)에 사용량을 저장합니다. Crush는 신뢰할 수 있는 메시지별 또는 모델별 토큰 집계를 제공하지 않으므로, Tokscale은 루트 세션의 세션 수준 비용 합계만 가져옵니다. 레코드는 model=session-total로 표시되며 토큰 분류는 0입니다.

Synthetic (synthetic.new)

Synthetic은 기존 에이전트 세션을 후처리하여 재귀속합니다. hf: 접두사 모델 ID 또는 synthetic / glhf / octofriend provider를 감지하면 해당 메시지를 synthetic 소스로 처리합니다.

또한 ~/.local/share/octofriend/sqlite.db를 감지해 토큰 정보가 있는 레코드를 파싱합니다.

가격

Tokscale은 LiteLLM의 가격 데이터베이스에서 실시간 가격을 가져옵니다.

동적 폴백: LiteLLM에 아직 없는 모델(예: 최근 출시된 모델)은 OpenRouter의 엔드포인트 API에서 자동으로 가격을 가져옵니다.

Cursor 모델 가격: LiteLLM과 OpenRouter 모두에 없는 최신 모델(예: gpt-5.3-codex)은 Cursor 모델 문서에서 가져온 하드코딩 가격을 사용합니다. 이 오버라이드는 모든 업스트림 소스 다음에, 퍼지 매칭 이전에 확인되므로 실제 업스트림 가격이 사용 가능해지면 자동으로 양보합니다.

캐싱: 가격 데이터는 1시간 TTL로 디스크에 캐시되어 빠른 시작을 보장합니다:

• LiteLLM 캐시: ~/.cache/tokscale/pricing-litellm.json
• OpenRouter 캐시: ~/.cache/tokscale/pricing-openrouter.json (지원 제공자의 모델에 대한 작성자 가격 정보를 캐시)

가격 포함 항목:

• 입력 토큰
• 출력 토큰
• 캐시 읽기 토큰 (할인)
• 캐시 쓰기 토큰
• 추론 토큰 (o1과 같은 모델용)
• 구간별 가격 (200k 토큰 이상)

기여

기여를 환영합니다! 다음 단계를 따르세요:

1. 저장소 포크
2. 기능 브랜치 생성 (git checkout -b feature/amazing-feature)
3. 변경 사항 작성
4. 테스트 실행 (cd packages/core && bun run test:all)
5. 변경 사항 커밋 (git commit -m 'Add amazing feature')
6. 브랜치에 푸시 (git push origin feature/amazing-feature)
7. Pull Request 열기

개발 가이드라인

• 기존 코드 스타일 따르기
• 새로운 기능에 테스트 추가
• 필요에 따라 문서 업데이트
• 커밋은 집중적이고 원자적으로 유지

감사의 글

• 영감을 준 ccusage, viberank, Isometric Contributions
• 터미널 UI 프레임워크 Ratatui
• 반응형 렌더링을 위한 Solid.js
• 가격 데이터를 위한 LiteLLM
• Rust/Node.js 바인딩을 위한 napi-rs
• 2D 그래프 참조를 위한 github-contributions-canvas

라이선스

MIT © Junho Yeo

이 프로젝트가 흥미롭다면 **스타(⭐)**를 눌러주세요.
GitHub에서 저를 팔로우하고 함께 빌드해도 좋아요. (이미 1.1k+명이 탑승해 있어요!)