JingbiaoMei/Tokdash
JingbiaoMei/Tokdash has 92 GitHub stars and 22 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-17 03:10 UTC. Last push 2026-11-10.
What you can do
- Exact token counts: Input/Output/Cache token breakdowns
- Session explorer: per-session drill-down
- Contribution calendar: 2D heatmap + 3D isometric view with Tokens/Cost/Messages metrics
- Report tab: a week / month / year-to-date report of your own agent activity, with a shareable card for each tier of detail. Every export writes a light and a dark PNG
측정된 스타 증가
- in 24h
- 0
- in 7 days
- 기록 수집 중
- in 15 days
- 기록 수집 중
- in 1 month
- 기록 수집 중
서로 겹치는 기간의 순증가량이며 일별 합계가 아닙니다. 측정값이 없으면 비워 둡니다. 스타는 관심도를 나타내며 품질을 보장하지 않습니다.
소개
Agent Dashboard: Visualization and analytics for Sessions and Quota Usage. Track, analyze, and optimize token usage across providers with heatmaps, cost tracking, token counting and quota resets..
개발 도구README_KO.md
OriginalEnglish | 中文 | 日本語 | 한국어 | Español | Português
AI 코딩 도구를 위한 로컬 토큰·비용 대시보드
설치 없이 바로 체험 → tokdash.github.io/demo
[!NOTE] 여러 기계를 하나의 대시보드에서. 설정에서 WSL, Mac 또는 다른 기기에서 실행 중인 Tokdash 인스턴스를 추가하세요. 모든 뷰는 선택한 것을 합산하고, Servers 탭은 기계를 나란히 비교하며, Quota 탭은 각 제공자의 윈도우 바와 리셋 카운트다운을 기계별로 묶어 보여줍니다. 원격 접근 → · 쿼터 추적 →
같은 저자의 다른 프로젝트: Cosyncing. 에이전트를 동기화하고 제어하세요 — CLI에서 GUI까지, 데스크톱에서 휴대폰까지. Cosyncing은 여러분 자신의 네트워크에서 코딩 에이전트를 동기화합니다.
목차
빠른 시작
pipx install tokdash
tokdash setup
끝입니다. tokdash setup이 런타임을 감지하고, 필요하면 관리형 런타임을 설치한 뒤
로컬 서비스를 등록하고 대시보드 주소 —— http://127.0.0.1:55423 —— 를
출력합니다. 전체 옵션, 첫 실행 안내, 업데이트 방법은
설치 및 실행에 있습니다. 먼저 둘러보고 싶다면
라이브 데모가 실제 UI로 동작합니다.
하나의 패키지, 네 가지 뷰
하나의 로컬 패키지, 하나의 로컬 데이터 인덱스 — 그리고 이를 읽는 네 가지 방법. 모든 인터페이스가 여러분 자신의 기기에서 동일한 세션 로그를 파싱하므로, 브라우저 대시보드, 터미널, 메뉴 막대, 에이전트의 상태줄이 언제나 동일한 수치를 보여줍니다.
| 뷰 | 무엇인가 | 이런 경우에 사용하세요 |
|---|---|---|
| WebUI | 전체 대시보드: Overview, Sessions, Stats, Report, Quota, Servers | 전체 조감, 차트, 드릴다운이 필요할 때 |
| TUI | tokdash tui — 터미널에서 7개 패널: Overview, Sessions, Stats, Report, Speed, Quota, Pricing |
터미널에 거주하며 브라우저 없이 수치가 필요할 때 |
| Companion | 네이티브 메뉴 막대(macOS) / 알림 영역(Windows) 앱 | 대시보드를 닫아둔 채 하루 종일 오늘의 지출과 쿼터를 눈에 담고 싶을 때 |
| 상태줄 | 에이전트 상태줄 안의 라이브 토큰/비용 항목 | 비용 티커를 정확히 타이핑하는 그 자리에 두고 싶을 때 |
WebUI
대시보드는 로컬 FastAPI 앱이 제공하는 단일 페이지로, 정확한 입력 / 캐시 / 출력 토큰 내역, 도구별·모델별 표, 기여 히트맵, 주/월/년 Report, 리셋 카운트다운이 있는 제공자별 Quota 윈도우, 여러 기계를 합치고 비교하는 Servers 탭을 담습니다. 스크린샷을 클릭하면 라이브 데모가 열립니다.
개요
|
사용 리포트
|
쿼터 추적
|
여러 서버, 하나의 합계
|
라이트와 다크는 OS 외관 설정을 따릅니다. 앱에는 17가지 스타일 테마, 라이트/다크 모드, PWA 설치, 6개 UI 언어(English / 中文 / 日本語 / 한국어 / Español / Português)가 기본 제공됩니다.
터미널 대시보드 (TUI)
터미널에 그대로 남겠다면? tokdash tui는 브라우저 없이 7개 패널 —— Overview, Sessions, Stats, Report, Speed, Quota, Pricing —— 을 열고, 동일한 로컬 인덱스를 읽습니다(옆에서 tokdash serve가 실행
중이면 디스크의 공유 데이터베이스도 함께 읽습니다). F1–F7로 패널을 이동하고, v로 목록에서 고릅니다.
TUI — Overview
|
TUI — Quota
|
tokdash tui
키보드
| 키 | 동작 |
|---|---|
q |
종료 |
r |
현재 패널 새로고침 |
F1–F7 |
Overview / Sessions / Stats / Report / Speed / Quota / Pricing(1 / 2 / 3은 기존대로 Overview / Report / Quota로 이동) |
v |
목록에서 패널 선택 |
t d w m y a |
공용 범위 지정: 오늘, 어제, 이번 주, 이번 달, 올해, 전체 |
p |
범위 추가(스트립의 More); Stats에서는 이전 연도 |
P |
Stats: 이후 연도(마지막 365일까지 복귀) |
c |
정확한 사용자 지정 날짜 범위 입력 |
[ / ] |
범위 전체 기간 단위 앞 / 뒤로 이동 — 미래로는 이동하지 않음 |
0 |
오늘로 복귀 |
/ |
포커스된 표에서 검색 |
s |
포커스된 표의 정렬 순환 |
enter / esc |
선택한 행 열기 / 닫기 |
h |
소스 선택(Sessions 및 Speed) |
H |
Speed의 소스를 하나씩 순환 |
k |
Speed 계열 선택 |
x |
측정 윈도우 세트 전환(Speed) |
b |
Speed 버킷 단위 전환 |
u |
쿼터 폴링(Quota 패널 전용) |
? |
모든 키를 표시하는 도움말 오버레이 |
일회성 리포트 CLI
파이프나 스크립트로 쓸 수 있는 일회성 리포트:
tokdash report --period week
기간은 위치 인자가 아니라 플래그입니다. 허용 값: today (기본), week,
month, year, all, 일수 숫자, 또는 Nd/Nw/Nm/Ny 축약형. week, month,
year는 웹 Report 탭이 표시하는 달력 기준 윈도우와 동일합니다. tokdash report는
tokdash export와 동일한 규칙에 따라 --json, --pretty, --output <file>도
받습니다.
Companion 상태표 앱
macOS용 네이티브 메뉴 막대 앱이자 Windows용 알림 영역 앱으로 동작하는 선택적 앱입니다. 대시보드를 열어두지 않고도 Tokdash 서비스를 컴팩트한 읽기 전용 뷰로 확인할 수 있습니다.
|
|
| macOS 메뉴 막대 | Windows 알림 영역 |
Windows — Microsoft Store (권장, Microsoft 서명, Windows 11 필요):
직접 다운로드 — 최신 companion 릴리스:
유니버설 DMG(arm64 + x86_64, macOS 14 이상)와 셀프컨테인드 포트어블 ZIP
(x64, Windows 11; Windows on Arm은 x64 에뮬레이션으로 사용 가능).
표시되는 내용과 설정 방식
- 오늘의 비용, 토큰, 메시지, 월 누적 사용량
- 여러 Tokdash 엔드포인트의 합계와 서버별 그룹 쿼터
- Codex, Claude, Kimi, MiniMax, Antigravity, Grok, Z.ai 쿼터 윈도우
- 상대적 리셋 시간과 선택적 저쿼터 알림
- 시스템 언어 감지 및 English, 简体中文, 日本語, 한국어, Español, Português
- 텔레메트리, 자격 증명 탐색, 포트 스캔, 직접 로그 파싱 없음
설정: Tokdash 1.5.2 이상(설치 및 실행)을 실행하고 Companion을
설치하면 기본적으로 http://127.0.0.1:55423에 연결됩니다 — 설정에서 프라이빗
Tailscale Serve URL을 포함해 명시적 엔드포인트를 추가, 테스트, 이름 붙이기,
제거할 수 있습니다. Companion은 사용자가 구성한 엔드포인트에만 접촉하며, 저쿼터
알림과 로그인 시 자동 실행은 모두 옵트인입니다.
[!WARNING] GitHub Releases 바이너리는 서명되지 않았습니다. macOS Gatekeeper와 Windows SmartScreen에서 미지 발신자 경고가 표시됩니다. 이 저장소에서만 다운로드하고, 포함된
SHA256SUMS를 확인한 후, 릴리스를 신뢰할 때에만 계속하세요. Microsoft Store 빌드는 Microsoft 서명이 되어 있어 영향을 받지 않으며, macOS 서명과 노타리제이션은 이후 릴리스에서 계획되어 있습니다.
체크섬, 업데이트, 제거 안내는 companion 릴리스 가이드를 참조하세요.
상태줄
로컬 API로 코딩 에이전트의 상태줄 항목에 실시간 토큰/비용 통계를 표시할 수 있습니다:
완성된 템플릿(bash 및 PowerShell), 설치/구성, 엔드포인트 참조는
**docs/guides/statusline/**에 있습니다.
설치 및 실행
플랫폼 지원
- Linux (WSL2 포함): 지원
- macOS: 지원
- Windows (네이티브): 실험적
사전 요구 사항: Python 3.10 이상 및 하나 이상의 지원 클라이언트.
설치
권장되는 격리 설치:
pipx install tokdash
pipx를 사용하지 않는다면:
python3 -m pip install --user tokdash
첫 실행
온보딩 마법사를 실행하세요:
tokdash setup
마법사는 플랫폼이 지원하는 경우 되돌릴 수 있는 사용자 수준 백그라운드 서비스를
구성한 뒤 대시보드 URL(기본: http://127.0.0.1:55423)을 표시합니다. 지원되는
서비스 매니저가 없으면 설정 상태를 기록하고 포어그라운드 실행 안내를 표시합니다.
localhost 우선 기본값을 사용하며, 로컬 서비스에 sudo가 필요 없고, 나중에
--purge로 언설치하지 않는 한 사용량 히스토리를 유지합니다.
에이전트, 스크립트, 번들에서 비대화형으로 설정하려면 tokdash setup --auto --json을
실행하세요. 설정이 무엇을 바꿀지 미리 보려면 tokdash setup --dry-run을 실행하세요.
모든 네트워크 인터페이스에 쓰기 비활성화 상태로 대시보드를 명시적으로 노출하려면
tokdash setup --bind 0.0.0.0을 실행하세요. 먼저 원격 접근
가이드를 검토하세요.
그다음 설치를 확인하세요:
tokdash doctor
doctor는 런타임, 백그라운드 서비스, 설정된 포트, 데이터 경로, 업데이트 확인
상태를 점검합니다. 자동화에는 tokdash doctor --json을 사용하세요.
업데이트 또는 제거
tokdash update # 관리 대상 런타임을 업그레이드하고 가능하면 서비스를 재시작
tokdash uninstall # setup이 만든 것만 정확히 되돌림. 기본적으로 사용량 히스토리 유지
update는 Tokdash가 안전하게 관리할 수 있는 설치 방식만 구동합니다. 런타임이
Tokdash가 소유하지 않는 패키지 매니저로 설치된 경우, 그 환경을 건드리지 않고
정확한 수동 안내를 표시합니다.
기존 설치: v1.0 이전에서 마이그레이션
온보딩 플로우 이전부터 Tokdash를 설치한 경우, 먼저 업그레이드하세요:
pipx upgrade tokdash
# 또는: python3 -m pip install --user -U tokdash
그다음 백그라운드 서비스 관리를 Tokdash에 맡기려면 tokdash doctor와
tokdash setup을 실행하세요. 이미 손으로 쓴 systemd나 launchd 서비스가 있으면
setup은 그것을 묵시적으로 교체하지 않습니다: 마커가 없는 tokdash.service /
plist 파일은 기본적으로 거부합니다. 그 서비스를 계속 직접 관리하거나, setup 전에
제거하거나, tokdash setup --dry-run을 확인한 뒤 tokdash setup --force를
실행하세요. --force는 포트 55423을 차지하고 있지만 새 /health 지문을 노출하지
않는 1.0 이전 서비스도 처리합니다: 기존 tokdash.service를 다시 작성하고
재시작합니다. 서비스 생성을 건너뛰려면 tokdash setup --no-service를 사용하세요.
현재 설정이 conda/시스템/사용자 pip 인터프리터를 사용하고 있고, 향후 업그레이드를
tokdash update가 관리하게 하려면 서비스를 Tokdash의 setup 소유 venv로
마이그레이션하세요:
# 곧 실행할 tokdash 명령을 업그레이드. 예:
python3 -m pip install --user -U tokdash
# 또는, conda base 설치인 경우:
conda run -n base python -m pip install -U tokdash
tokdash setup --runtime venv --force
tokdash doctor
이로써 사용량 히스토리는 ~/.tokdash 아래에 유지되고, 사용자 서비스는
~/.tokdash/runtime/python-venv/bin/python -m tokdash를 실행하도록 다시
작성되며, 이후 tokdash update가 해당 관리 venv를 업그레이드하고 서비스를
재시작하게 됩니다. pipx로 설치했다면 pipx 런타임을 그대로 유지한 채 tokdash update나 pipx upgrade tokdash로 업그레이드해도 됩니다.
포어그라운드 폴백
일회성 포어그라운드 프로세스만 필요할 때:
tokdash serve
http://127.0.0.1:55423을 엽니다. 기본 포트가 사용 중이면 tokdash serve --port <port>를 사용하세요. 기본적으로 tokdash serve는 시작 시 브라우저에서
대시보드를 한 번 엽니다. 끄려면 --no-open을 넘기세요. 명령어를 붙이지 않은
tokdash는 명령 헬프를 출력하고 종료하기만 합니다 — 더 이상 몰래 tokdash serve를
시작하지 않습니다.
온보딩 전체 상세 — 런타임 선택, WSL/systemd 동작, macOS launchd, Tailscale,
번들링, 업데이트 확인, 안전한 제거 동작 — 는
**docs/guides/ONBOARDING.md**를 참조하세요.
Tailscale Serve, SSH 포워딩, 명시적 네트워크 바인딩을 통한 원격 접근은
**docs/guides/REMOTE_ACCESS.md**를 참조하세요.
기능
- 정확한 토큰 수: 입력/출력/캐시 토큰 내역
- 세션 탐색기: 세션별 드릴다운
- 기여 캘린더: Tokens/Cost/Messages 지표가 있는 2D 히트맵 + 3D 등각 뷰
- Report 탭: 본인 에이전트 활동을 주 / 월 / 연초 누적 기준으로 정리한 보고서. 상세 단계별로 공유 가능한 카드를 제공하며, 내보낼 때마다 밝은 색과 어두운 색 PNG 두 장을 함께 씁니다
- Quota 탭: 아홉 제공자의 구독 윈도우 바와 리셋 카운트다운. Codex 윈도우는 로컬 로그로 바로 동작하며, 그 외 대다수 소스에는 옵트인 라이브 폴링이 필요합니다
- 터미널 대시보드 [신규]:
tokdash tui— 브라우저 없이 터미널에서 Overview, Sessions, Stats, Report, Speed, Quota, Pricing - Companion 상태표 앱: macOS 메뉴 막대나 Windows 알림 영역에서 지출과 구독 쿼터 확인 — Windows는 Microsoft Store 제공
- 상태줄 통합: Claude Code의 상태줄(또는 로컬 HTTP 엔드포인트에 도달할 수 있는 어떤 에이전트든)에 실시간 토큰 사용량 표시기
- 멀티 서버 뷰: 설정에서 WSL, macOS, 기타 Tokdash 서버를 추가. 임의의 선택 사용량을 합치되 쿼터는 머신별로 그룹화. 원격 접근 참조.
- 테마와 앱 마감: 17가지 스타일 테마, 라이트/다크 모드, PWA 설치 지원, 6개 언어 UI
지원 클라이언트
Tokdash는 27개 지원 에이전트의 로컬 세션 로그를 읽습니다 — 위의 픽토그램 행이 이름들을 보여줍니다. 전체 매트릭스(사용량·비용 / Session Explorer 커버리지, 클라이언트별 데이터 경로, 오버라이드, 소스별 계상 노트)은 **지원 클라이언트**에 있습니다.
쿼터 추적 (선택사항)
Quota 탭은 아홉 제공자의 구독 이용률 윈도우와 리셋 카운트다운을 표시합니다. Codex의 5시간/주간 윈도우는 로컬 로그로 바로 동작합니다(추정치로만 여기세요). 정확한 Codex 소비량과 그 외 모든 제공자 — Claude Code, Antigravity, MiniMax, Kimi Code, Grok, Z.ai, OpenCode Go, Command Code — 는 옵트인 라이브 폴링에서 나옵니다: Tokdash는 CLI가 이미 가진 로그인으로 각 제공자 자신의 쿼터 엔드포인트를 호출합니다. 기본값은 꺼짐, 제공자별 동의, 결과는 로컬 데이터베이스에 저장됩니다.
동의 명령, 마스터 스위치, 폴링 주기, 제공자별 자격 증명 노트는
**docs/reference/QUOTA.md**를 참조하세요.
비용 정확도 안내
토큰 수는 각 클라이언트가 로컬에 로그하는 내용에 따라 달라집니다. 비용은 기본적으로 번들된 가격 데이터베이스(src/tokdash/pricing_db.json)에서, 있으면 저장된 대시보드 가격 오버라이드(<data_dir>/pricing_db.json)에서 계산됩니다. 어느 쪽이든 실제 제공자 가격보다 늦을 수 있습니다 — 추정치로 쓰고, 중요하면 청구 출처와 대조하세요.
히스토리 보존
[!IMPORTANT] 히스토리를 보존하세요. Claude Code와 Gemini CLI는 기본적으로 약 30일 이전의 로컬 세션을 삭제하므로, Tokdash의 이전 달들이 조용히 줄어듭니다.
Tokdash는 각 클라이언트의 로컬 세션 로그를 읽으며, 로컬 SQLite 인덱스는 인덱싱되기 전에 삭제된 로그를 되찾을 수 없습니다. 기본적으로 오래된 세션을 삭제하는 지원 클라이언트는 두 곳뿐이고, 둘 다 한 줄로 수정됩니다:
- Claude Code:
~/.claude/settings.json(그리고 대체CLAUDE_CONFIG_DIR이 있으면)에{ "cleanupPeriodDays": 3650 }을 추가하세요. - Gemini CLI:
~/.gemini/settings.json에서{ "general": { "sessionRetention": { "enabled": false } } }를 설정하세요(워크스페이스 설정이 사용자 설정보다 우선합니다).
나머지 모든 지원 클라이언트는 기본적으로 히스토리를 무기한 유지합니다. 클라이언트별 전체 조사, 수정 상세, 로컬 SQLite 인덱스가 보존하는 것과 보존하지 못하는 것의 전체는 **docs/reference/HISTORY_RETENTION.md**를 참조하세요.
로드맵
docs/development/ROADMAP.md를 참조하세요.
기여 / 보안
- 기여 가이드:
docs/CONTRIBUTING.md - 보안 정책:
docs/SECURITY.md
문서
완전한 문서는 docs/(인덱스에서 시작)에 있으며, 다음으로 나뉩니다:
- guides/ — 작업 중심 설정: 온보딩, 원격 접근, 상태줄, 백그라운드 서비스.
- reference/ — 참조 자료: API 참조, 구성, 쿼터 내부 동작, 지원 클라이언트, 히스토리 보존.
- development/ — 체인지로그, 릴리스, 로드맵, 공개
technical-notes/.
라이선스
MIT License - LICENSE 참조.
