README.ko.md

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

Tip

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

	GitHub에서 @junhoyeo를 팔로우하고 더 많은 프로젝트를 만나보세요. AI, 인프라 등 다양한 분야를 다룹니다.
	Discord에서 함께해요 — 세계 최고의 바이버들과 어울리세요.

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

Overview	Models

Daily Summary	Stats

Frontend (3D Contributions Graph)	Wrapped 2025

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

개요

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

로고	클라이언트	데이터 위치	지원 여부
	OpenCode	~/.local/share/opencode/opencode.db (1.2+, opencode-stable.db 등 모든 채널 포함) 또는 ~/.local/share/opencode/storage/message/	✅ 지원
	Claude Code	~/.claude/projects/	✅ 지원
	OpenClaw	~/.openclaw/agents/ (+ 레거시: .clawdbot, .moltbot, .moldbot)	✅ 지원
	Codex CLI	~/.codex/sessions/	✅ 지원
	GitHub Copilot CLI	~/.copilot/otel/*.jsonl (+ COPILOT_OTEL_FILE_EXPORTER_PATH)	✅ 지원
	Hermes Agent	$HERMES_HOME/state.db (폴백: ~/.hermes/state.db)	✅ 지원
	Gemini CLI	$GEMINI_CLI_HOME/tmp/*/chats/*.json (폴백: ~/.gemini/tmp/*/chats/*.json)	✅ 지원
	Cursor IDE	~/.config/tokscale/cursor-cache/를 통한 API 동기화	✅ 지원
	Amp (AmpCode)	~/.local/share/amp/threads/	✅ 지원
	Codebuff	~/.config/manicode/ (+ manicode-dev, manicode-staging; CODEBUFF_DATA_DIR로 오버라이드 가능)	✅ 지원
	Droid (Factory Droid)	~/.factory/sessions/	✅ 지원
	Pi	~/.pi/agent/sessions/ and ~/.omp/agent/sessions/ (Oh My Pi)	✅ 지원
	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/)	✅ 지원
	Kilo CLI	~/.local/share/kilo/kilo.db	✅ 지원
	Mux	~/.mux/sessions/	✅ 지원
	Crush	$XDG_DATA_HOME/crush/projects.json (프로젝트 레지스트리, 기본값: ~/.local/share/crush/projects.json)	✅ 지원
	Goose	~/.local/share/goose/sessions/sessions.db (+ macOS Application Support, 레거시 Block/goose 경로; GOOSE_PATH_ROOT로 오버라이드 가능)	✅ 지원
	Google Antigravity	tokscale antigravity sync로 ~/.config/tokscale/antigravity-cache/sessions/*.jsonl에 캐싱 (로컬 언어 서버 RPC 사용)	✅ 지원
	Trae IDE / Trae Solo (국제판)	tokscale trae sync로 ~/.config/tokscale/trae-cache/sessions/*.json에 캐싱 (공식 API의 계정 단위 사용량)	✅ 지원
	Zed Agent	~/.local/share/zed/threads/threads.db (macOS: ~/Library/Application Support/Zed/threads/threads.db; Windows: %LOCALAPPDATA%/Zed/threads/threads.db; 호스팅된 Zed 모델 전용, 외부 ACP 에이전트 제외)	✅ 지원
	Kiro	~/.kiro/sessions/cli/*.json (+ *.jsonl) 및 ~/.local/share/kiro-cli/data.sqlite3 (macOS: ~/Library/Application Support/kiro-cli/data.sqlite3)	✅ 지원
	gajae-code (gjc)	~/.gjc/agent/sessions/ (GJC_CODING_AGENT_DIR, GJC_CONFIG_DIR, PI_CONFIG_DIR로 오버라이드 가능; Linux/macOS에서는 $XDG_DATA_HOME/gjc/sessions/도 확인)	✅ 지원
	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 명령어
  • Antigravity 명령어
  • Trae 명령어
  • 예시 출력
  • 설정
  • 환경 변수
• 프론트엔드 시각화
  • 기능
  • 프론트엔드 실행
• 소셜 플랫폼
  • 기능
  • GitHub 프로필 임베드 위젯
  • GitHub 프로필 뱃지
  • 시작하기
  • 데이터 검증
• Wrapped 2025
  • 명령어
  • 포함 내용
• 개발
  • 사전 요구사항
  • 실행 방법
• 지원 플랫폼
  • 네이티브 모듈 타겟
  • Windows 지원
• 세션 데이터 보존
• 데이터 소스
• 가격
• 기여
  • 개발 가이드라인
• 감사의 글
• 라이선스

기능

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

설치

빠른 시작

# npx로 바로 실행
npx tokscale@latest

# 또는 bunx 사용
bunx tokscale@latest

# 별칭 설치 없이 Deno 사용
deno x npm: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 모드는 다음을 제공합니다:

• 6개 뷰: 개요 (차트 + 상위 모델), 모델, 일별, 시간별, 통계 (기여 그래프), 에이전트
• 키보드 내비게이션:
  • ←/→/Tab/BackTab: 뷰 전환
  • ↑/↓ 또는 Home/End: 목록 탐색
  • Enter: 일별 상세 보기 (Daily 탭) / 그래프 셀 선택 (Stats 탭)
  • Esc 또는 Backspace: 다이얼로그 닫기 / 상세 보기 나가기
  • c/d/t: 비용/날짜/토큰별 정렬
  • j: 오늘로 이동
  • s: 소스 선택 다이얼로그 열기
  • g: 그룹 기준 선택 다이얼로그 열기 (모델, 클라이언트+모델, 클라이언트+프로바이더+모델)
  • h: Daily/Hourly 차트 단위 전환 (Overview 탭)
  • v: Table/Profile 뷰 전환 (Hourly 탭)
  • y: 선택된 행을 클립보드에 복사
  • p: 9가지 색상 테마 순환
  • r: 데이터 새로고침; Shift+R로 자동 새로고침 토글; +/-로 간격 조정
  • e: JSON으로 내보내기
  • q 또는 Ctrl+C: 종료
• 마우스 지원: 탭, 버튼, 필터 클릭
• 테마: 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

플랫폼별 필터링

--client (단축형 -c) 플래그로 하나 이상의 클라이언트로 리포트 범위를 좁힐 수 있습니다. 반복 사용 가능하며 콤마로 구분된 값도 지원하고, 모든 리포트 명령에서 동작합니다:

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

# 콤마로 구분: 여러 클라이언트 동시 필터
tokscale --client opencode,claude

# 반복: 같은 효과 (쉘 alias와 함께 쓰기 좋음)
tokscale -c opencode -c claude

# Cursor IDE는 사전에 `tokscale cursor login` 필요
tokscale --client cursor

# Synthetic (synthetic.new) 은 다른 에이전트 세션에서 검출됨
tokscale --client synthetic

# 다른 필터와 조합
tokscale --client opencode,claude --week --json

가능한 값: opencode, claude, codex, copilot, gemini, cursor, amp, codebuff, droid, openclaw, hermes, pi, kimi, qwen, roocode, kilocode, kilo, mux, crush, goose, antigravity, zed, kiro, trae, gjc, synthetic.

Deprecation 안내: 기존 단일 클라이언트 플래그 (--opencode, --claude, --codex 등)는 하위 호환성을 위해 여전히 동작하지만 --help에서 숨겨졌으며 다음 메이저 릴리스에서 제거됩니다. 가능한 한 --client로 마이그레이션하세요. 인터랙티브 터미널에서 레거시 플래그를 사용하면 한 줄 경고가 출력됩니다.

날짜 필터링

날짜 필터는 리포트를 생성하는 모든 명령어에서 작동합니다 (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 --client claude --json
tokscale monthly --month --benchmark

참고: 날짜 필터는 로컬 타임존을 사용합니다. --since와 --until 모두 해당 날짜를 포함합니다. v2.2.0 참고: 세션 활성 시간의 일별 버킷도 로컬 타임존을 사용하므로, UTC가 아닌 환경에서는 활성 시간 날짜가 UTC 일 경계가 아니라 로컬 토큰/비용 리포트 날짜와 맞춰질 수 있습니다.

가격 조회

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

# 모델 가격 조회
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 --client 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 계정에 대한 전체 액세스 권한을 부여합니다.

Antigravity 명령어

Antigravity 동기화는 현재 macOS와 Linux에서만 지원됩니다. Antigravity가 활성화된 에디터가 실행 중이고 로컬 언어 서버를 사용할 수 있을 때만 동작하며, tokscale은 해당 로컬 언어 서버에서 사용량을 읽어 정규화된 아티팩트를 로컬에 캐시합니다.

# 실행 중인 Antigravity 언어 서버를 tokscale이 인식하는지 확인
tokscale antigravity status

# 로컬 Antigravity 언어 서버에서 사용량을 tokscale 캐시로 동기화
tokscale antigravity sync

# 캐시된 Antigravity 아티팩트 삭제
tokscale antigravity purge-cache

캐시 위치: ~/.config/tokscale/antigravity-cache/

동작 방식: tokscale antigravity sync는 로컬 Antigravity 세션 후보를 검색하고, 로컬 언어 서버 RPC에서 확정된 사용량 데이터를 가져와, tokscale-core가 나중에 파싱할 수 있도록 정규화된 JSONL 아티팩트로 저장합니다. 가장 최신의 Antigravity 데이터를 반영하려면 리포트 실행 전에 sync를 먼저 실행하세요.

Trae 명령어

Trae(ByteDance의 AI IDE)는 두 국제판 제품군을 제공합니다. 사용량 데이터는 계정 단위로 공유되므로 tokscale은 하나의 trae 클라이언트로 표시합니다:

• --variant ide — Trae IDE (국제판)의 자격 증명 사용
• --variant solo — Trae Solo (국제판)의 자격 증명 사용

tokscale trae sync는 공식 query_user_usage_group_by_session API를 호출하고 원본 JSON을 로컬 캐시에 저장합니다. --variant solo / --variant ide는 login/logout에서 자격 증명 출처를 선택할 때만 사용하며, sync는 저장된 Trae 토큰으로 단일 trae 리포트 클라이언트를 갱신합니다.

# 로그인 (Trae 데스크톱 클라이언트에서 자격 증명 자동 감지)
tokscale trae login

# 수동 JWT 입력 (storage.json을 자동 감지할 수 없는 환경용)
tokscale trae login --manual --variant solo

# 어떤 변형에 자격 증명이 캐시되어 있는지 확인
tokscale trae status

# 최근 30일 사용량을 동기화
tokscale trae sync --since 30

# 특정 변형의 캐시된 자격 증명 삭제
tokscale trae logout --variant solo

캐시 위치: ~/.config/tokscale/trae-cache/

동작 방식: tokscale은 데스크톱 클라이언트의 iCubeAuthInfo://* blob(globalStorage/storage.json)을 복호화해 JWT를 얻거나, --manual로 붙여 넣은 JWT를 사용합니다. 이후 POST /trae/api/v1/pay/query_user_usage_group_by_session을 페이지 단위로 호출하고 원본 JSON을 저장합니다. 최신 Trae 데이터를 반영하려면 리포트 실행 전에 sync를 먼저 실행하세요.

중국판: 중국판(trae.com.cn)은 의도적으로 지원하지 않습니다. CN 백엔드는 세션 단위 사용량 조회 API를 공개하지 않습니다. 공식 엔드포인트가 제공되면 지원을 추가할 예정입니다.

예시 출력 (--light 버전)

설정

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

{
  "colorPalette": "blue",
  "includeUnusedModels": false,
  "defaultClients": ["opencode", "claude"]
}

설정	타입	기본값	설명
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)
defaultClients	string[]	[]	--client/-c 플래그를 전달하지 않을 때 적용되는 기본 클라이언트 필터. --client와 동일한 ID를 받습니다 (예: ["opencode", "claude", "synthetic"]). 알 수 없는 ID는 자동으로 무시됩니다. CLI 플래그가 있으면 이 목록은 완전히 무시됩니다 — 병합되지 않습니다.
light.writeCache	boolean	false	true이면 tokscale --light가 렌더링 직후 TUI 캐시를 원자적으로 덮어씁니다. CLI 플래그 --write-cache / --no-write-cache가 실행별로 우선합니다.
minutelyTabEnabled	boolean	false	TUI에 분 단위 Minutely 탭을 표시하고 데이터 로딩 중에 분 단위 집계를 수행합니다. 대부분의 사용자에게 분 단위 세분화는 틈새/진단 뷰이며, 대규모 데이터셋에서는 분 단위 버케팅에 무시할 수 없는 비용이 들기 때문에 기본적으로 비활성화되어 있습니다.

Minutely 탭 활성화

Minutely 탭은 토큰 사용량을 분 단위로 표시하며, 버스트 패턴 진단, 단일 세션 디버깅, autoRefreshEnabled와 함께 거의 실시간 모니터링에 가장 유용합니다. 분 단위 집계는 데이터 로딩 중 모든 파싱된 메시지를 처리하므로 대부분의 사용자에게는 불필요한 RAM과 CPU 비용이 발생합니다. 그래서 기본적으로 숨겨져 있습니다.

활성화하려면 ~/.config/tokscale/settings.json에서 minutelyTabEnabled를 true로 설정하세요:

{
  "minutelyTabEnabled": true
}

재시작 후 탭 스트립의 Hourly와 Stats 사이에 Minutely 탭이 나타나며, Tab / BackTab / Left / Right 내비게이션이 이를 순환합니다. 플래그를 다시 false로 설정하면 탭이 숨겨지고 집계도 다시 건너뜁니다.

캐시 디렉터리 레이아웃

재생성 가능한 CLI/TUI/가격/Wrapped 캐시는 ~/.config/tokscale/cache/ 아래에 저장됩니다 (TOKSCALE_CONFIG_DIR를 설정한 경우 ${TOKSCALE_CONFIG_DIR}/cache/). 통합 동기화 아티팩트는 ~/.config/tokscale/antigravity-cache/ 및 ~/.config/tokscale/trae-cache/ 같은 클라이언트별 캐시 루트에 저장됩니다:

• tui-data-cache.json — TUI 시작 캐시
• source-message-cache.bin + source-message-cache.lock — 소스 메시지 캐시와 락 파일
• pricing-litellm.json / pricing-openrouter.json — 가격 캐시
• opencode-migration.json — OpenCode 마이그레이션 기록
• fonts/, images/ — Wrapped 에셋 캐시

이 디렉터리는 삭제해도 안전합니다. 필요할 때 Tokscale이 다시 생성하고 채웁니다.

환경 변수

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

변수	기본값	설명
TOKSCALE_NATIVE_TIMEOUT_MS	300000 (5분)	nativeTimeoutMs 설정 오버라이드
TOKSCALE_CONFIG_DIR	unset	설정 디렉토리 루트(settings.json, star-cache.json, cache/, antigravity-cache/, trae-cache/ 위치)를 오버라이드합니다. 절대 경로 권장; 상대 경로는 프로세스 CWD 기준으로 해석됩니다. CI 샌드박스나 비기본 위치를 고정할 때 유용합니다. 설정되면 tokscale은 macOS 레거시 경로(~/Library/Application Support/tokscale/)로 폴백하지 않습니다.

# 예시: 매우 큰 데이터셋에 대한 타임아웃 증가
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, Copilot, Cursor, Gemini, Amp, Codebuff, Droid, OpenClaw, Hermes Agent, Pi, Kimi, Qwen, Roo Code, Kilo, Mux, Kilo CLI, Crush, Goose, Antigravity, Zed, Kiro, Trae, Gajae-Code, 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/index.ts

# 또는 레거시 CLI 모드 사용
cd packages/cli && bun src/index.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 --client 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 환경변수로 설정 가능 (소스)
Copilot CLI	~/.copilot/otel/	%USERPROFILE%\.copilot\otel\	OTEL 파일 내보내기 필요; COPILOT_OTEL_FILE_EXPORTER_PATH도 자동 수집
Hermes Agent	~/.hermes/	%USERPROFILE%\.hermes\	HERMES_HOME 환경변수로 설정 가능 (소스)
Gemini CLI	~/.gemini/	%USERPROFILE%\.gemini\	GEMINI_CLI_HOME 환경변수로 설정 가능
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/ and ~/.omp/	%USERPROFILE%\.pi\ and %USERPROFILE%\.omp\	모든 플랫폼에서 동일한 경로 (Pi 및 Oh My 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\	모든 플랫폼에서 동일한 경로
Codebuff	~/.config/manicode/projects/ (+ manicode-dev, manicode-staging)	%USERPROFILE%\.config\manicode\projects\	CODEBUFF_DATA_DIR 환경변수로 오버라이드
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 데이터 디렉토리 사용
Goose	~/.local/share/goose/sessions/ (+ macOS Application Support, 레거시 Block 경로)	%USERPROFILE%\.local\share\goose\sessions\	GOOSE_PATH_ROOT 환경변수로 설정 가능
Antigravity	~/.config/tokscale/antigravity-cache/sessions/	—	tokscale antigravity sync는 현재 macOS/Linux에서만 지원
Trae	~/.config/tokscale/trae-cache/sessions/	%APPDATA%\tokscale\trae-cache\sessions\	tokscale trae sync로 한 번 동기화; 설치된 Trae IDE 또는 Trae Solo 데스크톱 앱에서 자격 증명 자동 발견
Gajae-Code	~/.gjc/agent/sessions/	%USERPROFILE%\.gjc\agent\sessions\	GJC_CODING_AGENT_DIR로 설정 가능 (GJC_CONFIG_DIR/PI_CONFIG_DIR도 지원; Linux/macOS에서는 $XDG_DATA_HOME/gjc/sessions/도 확인)
Synthetic	다른 소스에서 재귀속	다른 소스에서 재귀속	hf: 모델 접두사 + synthetic provider 감지

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

Windows 전용 설정

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

• TUI 설정: %APPDATA%\tokscale\settings.json (플랫폼 기본값. TOKSCALE_CONFIG_DIR로 오버라이드 가능)
• 캐시: %APPDATA%\tokscale\cache\ (통합 캐시 루트)
• 레거시 캐시 경로: 이전 릴리스의 %USERPROFILE%\.cache\tokscale\ 같은 분리된 경로가 새 경로로 다시 생성 가능한 데이터가 기록될 때까지 남아 있을 수 있습니다.
• Cursor 자격 증명: %USERPROFILE%\.config\tokscale\cursor-credentials.json
• Trae 자격 증명 및 동기화된 사용량: %APPDATA%\tokscale\trae-cache\
• Tokscale 계정 자격 증명: %USERPROFILE%\.config\tokscale\credentials.json

세션 데이터 보존

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

플랫폼	기본값	설정 파일	비활성화 설정	출처
Claude Code	⚠️ 30일	~/.claude/settings.json	"cleanupPeriodDays": 9999999999	문서
Gemini CLI	비활성화됨	$GEMINI_CLI_HOME/settings.json (폴백: ~/.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_CLI_HOME/settings.json (폴백: ~/.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 파일로 폴백합니다.

OpenCode는 빌드된 릴리스 채널에 따라 DB 파일명을 결정합니다: latest, beta 채널은 opencode.db를 사용하고, 나머지 채널은 opencode-<channel>.db (예: opencode-stable.db, opencode-nightly.db)를 사용합니다. Tokscale은 모든 변형을 스캔하므로 여러 채널을 함께 사용하는 경우에도 통합된 뷰를 제공합니다.

각 메시지 포함 내용:

{
  "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}}}}

Copilot CLI

위치: ~/.copilot/otel/*.jsonl 또는 COPILOT_OTEL_FILE_EXPORTER_PATH에 명시된 경로

Copilot 지원은 파일로 내보낸 OpenTelemetry JSONL을 읽습니다. Copilot을 실행하기 전에 활성화하세요:

export COPILOT_OTEL_ENABLED=true
export COPILOT_OTEL_EXPORTER_TYPE=file
mkdir -p "$HOME/.copilot/otel"
export COPILOT_OTEL_FILE_EXPORTER_PATH="$HOME/.copilot/otel/copilot-otel-$(date +%Y%m%d-%H%M%S).jsonl"

PowerShell:

$otelDir = "$HOME/.copilot/otel"
New-Item -ItemType Directory -Force -Path $otelDir | Out-Null
$env:COPILOT_OTEL_ENABLED = "true"
$env:COPILOT_OTEL_EXPORTER_TYPE = "file"
$env:COPILOT_OTEL_FILE_EXPORTER_PATH = Join-Path $otelDir ("copilot-otel-{0}.jsonl" -f (Get-Date -Format "yyyyMMdd-HHmmss"))

타임스탬프가 포함된 파일명을 사용하면 각 Copilot 세션이 하나의 거대한 OTEL 로그에 누적되지 않고 새 파일에 기록됩니다.

Tokscale은 chat span을 토큰 집계의 출처로 취급하고, 도구 span과 누적 메트릭은 1단계에서 무시합니다:

{"type":"span","name":"chat gpt-5.4-mini","attributes":{"gen_ai.operation.name":"chat","gen_ai.response.model":"gpt-5.4-mini","gen_ai.conversation.id":"session-id","gen_ai.usage.input_tokens":1234,"gen_ai.usage.output_tokens":567,"gen_ai.usage.cache_read.input_tokens":890,"gen_ai.usage.reasoning.output_tokens":123}}

Copilot의 OTEL 페이로드는 현재 안정적인 워크스페이스 메타데이터를 노출하지 않으므로, Copilot 행은 워크스페이스 속성 없이 표시될 수 있습니다. Tokscale은 가능한 경우 보고된 모델로부터 해당 행의 가격을 책정하며, github.copilot.cost를 직접 신뢰하지 않습니다.

Gemini CLI

위치: $GEMINI_CLI_HOME/tmp/{projectHash}/chats/*.json (폴백: ~/.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 명령어를 참조하세요.

Antigravity

위치: ~/.config/tokscale/antigravity-cache/sessions/*.jsonl (로컬 Antigravity 언어 서버 RPC를 통해 동기화)

Antigravity 데이터는 루트 명령에서 자동으로 가져오지 않습니다. Antigravity가 활성화된 에디터가 열려 있는 동안 tokscale antigravity sync를 실행해 로컬 캐시를 새로 고친 다음, 캐시된 JSONL 아티팩트에 대해 일반적인 tokscale 리포트와 필터를 사용하세요.

Trae

위치: ~/.config/tokscale/trae-cache/sessions/*.json (공식 사용량 API를 통해 동기화)

Trae 데이터는 루트 명령에서 자동으로 가져오지 않습니다. 먼저 tokscale trae login을 실행한 뒤, 리포트 전에 tokscale trae sync 또는 tokscale trae sync --since 30을 실행하세요. Tokscale은 동기화된 API dump를 세션 수준 레코드로 파싱하고 Trae가 반환한 비용 합계를 보존합니다.

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}}

Hermes Agent

위치: $HERMES_HOME/state.db (폴백: ~/.hermes/state.db)

Hermes는 세션 수준 사용량을 SQLite sessions 테이블에 저장합니다. Tokscale은 model이 존재하고 토큰 또는 비용 합계가 0이 아닌 행을 가져오며, started_at을 타임스탬프로 사용하고, message_count를 보존하며, actual_cost_usd를 estimated_cost_usd보다 우선합니다.

Pi

위치: ~/.pi/agent/sessions/<encoded-cwd>/*.jsonl 및 ~/.omp/agent/sessions/<encoded-cwd>/*.jsonl (Oh My Pi)

세션 헤더와 메시지 항목을 포함하는 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입니다.

Goose

위치: ~/.local/share/goose/sessions/sessions.db (~/Library/Application Support/goose/, ~/Library/Application Support/Block/goose/, ~/.local/share/Block/goose/도 스캔; GOOSE_PATH_ROOT로 오버라이드 가능)

Goose는 세션별 사용량을 SQLite sessions.db에 저장합니다. Tokscale은 model_config_json에서 모델, provider_name에서 공급자, 그리고 세션별로 누적된 입력/출력 토큰 합계를 추출합니다. 추론 토큰은 해당 컬럼이 채워져 있을 때 추정됩니다.

Codebuff

위치: ~/.config/manicode/projects/<project>/chats/<chatId>/chat-messages.json (manicode-dev 및 manicode-staging 채널도 스캔; CODEBUFF_DATA_DIR로 오버라이드 가능)

Codebuff(이전 Manicode)는 채팅별 JSON 파일을 저장합니다. Tokscale은 metadata.usage, metadata.codebuff.usage 및 run-state의 messageHistory[*].providerOptions 폴백에서 토큰 사용량을 파싱하며, 부분적으로 갱신된 최신 항목이 실제 토큰 카운트를 가진 이전 항목을 가리지 않도록 히스토리를 역순으로 순회합니다. 메시지별 타임스탬프가 없을 때는 chat-id 디렉토리 이름, 마지막으로 파일 mtime으로 폴백합니다.

Gajae-Code (gjc)

위치: ~/.gjc/agent/sessions/<project-slug>/*.jsonl (GJC_CODING_AGENT_DIR로 에이전트 디렉토리 오버라이드 가능; GJC_CONFIG_DIR/PI_CONFIG_DIR에 agent/sessions를 붙인 경로도 확인하며, Linux/macOS에서는 $XDG_DATA_HOME/gjc/sessions/로 단축된 경로도 지원). 뎁스-2 패스별 서브에이전트 전사본(<slug>/<session>/N-*.jsonl)도 탐색합니다.

세션 헤더와 메시지 항목으로 구성된 JSONL 형식입니다. Tokscale은 어시스턴트 메시지만 처리하며, 메시지당 usage.cost.total(USD)이 있으면 그 값을 우선 사용하고, 없을 때만 토큰에서 비용을 재계산합니다:

{"type":"session","id":"S1","timestamp":"2026-01-01T00:00:00.000Z","cwd":"/work/proj"}
{"type":"message","id":"M1","timestamp":"2026-01-01T00:00:01.000Z","message":{"role":"assistant","model":"claude-sonnet-4","provider":"anthropic","usage":{"input":1000,"output":500,"cacheRead":0,"cacheWrite":0,"totalTokens":1500,"cost":{"input":0.1,"output":0.2,"total":0.3}}}}

메시지는 <세션 id>:<메시지 id>로 중복 제거됩니다(결정론적 폴백 포함). 재실행된 뎁스-1/뎁스-2 전사본은 한 번만 집계됩니다. service_tier_change 항목과 잘못된 형식의 줄은 줄 단위로 건너뜁니다.

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 캐시: ~/.config/tokscale/cache/pricing-litellm.json
• OpenRouter 캐시: ~/.config/tokscale/cache/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+명이 탑승해 있어요!)