{"id":42517862,"url":"https://github.com/mag123c/toktrack","last_synced_at":"2026-06-08T08:01:13.938Z","repository":{"id":334721245,"uuid":"1142477582","full_name":"mag123c/toktrack","owner":"mag123c","description":"Ultra-fast token \u0026 cost tracker for LLM Token Usage (e.g. Claude Code)","archived":false,"fork":false,"pushed_at":"2026-06-04T02:54:58.000Z","size":6577,"stargazers_count":151,"open_issues_count":1,"forks_count":13,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-04T03:04:44.558Z","etag":null,"topics":["ai-billing","ai-coding","ai-cost","ai-tools","anthropic","claude-code","cli","codex-cli","cost-monitor","cost-tracking","developer-tools","gemini-cli","llm","multi-cli","openai","rust","terminal","token-tracker","token-usage","tui"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/toktrack","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mag123c.png","metadata":{"files":{"readme":"README.ko.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["mag123c"]}},"created_at":"2026-01-26T13:17:10.000Z","updated_at":"2026-06-04T02:54:57.000Z","dependencies_parsed_at":"2026-02-01T08:04:18.846Z","dependency_job_id":null,"html_url":"https://github.com/mag123c/toktrack","commit_stats":null,"previous_names":["mag123c/toktrack"],"tags_count":80,"template":false,"template_full_name":null,"purl":"pkg:github/mag123c/toktrack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mag123c%2Ftoktrack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mag123c%2Ftoktrack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mag123c%2Ftoktrack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mag123c%2Ftoktrack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mag123c","download_url":"https://codeload.github.com/mag123c/toktrack/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mag123c%2Ftoktrack/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34053435,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-billing","ai-coding","ai-cost","ai-tools","anthropic","claude-code","cli","codex-cli","cost-monitor","cost-tracking","developer-tools","gemini-cli","llm","multi-cli","openai","rust","terminal","token-tracker","token-usage","tui"],"created_at":"2026-01-28T15:07:14.994Z","updated_at":"2026-06-08T08:01:13.929Z","avatar_url":"https://github.com/mag123c.png","language":"Rust","funding_links":["https://github.com/sponsors/mag123c"],"categories":["Applications","AI","claude-code","Monitoring and Cost Tracking"],"sub_categories":["Productivity","Agents","MCP Frameworks and Tooling"],"readme":"# toktrack\n\n[![CI](https://github.com/mag123c/toktrack/actions/workflows/ci.yml/badge.svg)](https://github.com/mag123c/toktrack/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/toktrack)](https://www.npmjs.com/package/toktrack)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n[English](README.md) | **한국어**\n\n\u003e **⚠️ 알고 계셨나요?** Claude Code는 **기본적으로 30일 후 세션 데이터를 삭제**합니다. 삭제되면 토큰 사용량과 비용 기록은 영원히 사라집니다 — 보존하지 않는 한.\n\n**비용 기록을 절대 잃지 않는 토큰 \u0026 비용 트래커.** 대부분의 도구는 매 실행마다 CLI 세션 파일을 다시 읽습니다 — 그래서 Claude Code가 30일 후 파일을 삭제하면 비용 기록도 함께 사라집니다. toktrack은 **영구 캐시**를 유지해 기록이 살아남습니다.\n\n**모든 AI 코딩 CLI**의 사용량을 한 곳에서 — Claude Code, Codex CLI, Gemini CLI, Qwen Code, OpenCode, PI Agent 통합 대시보드. Rust 기반이라 대용량 기록에서도 빠릅니다 (simd-json + rayon).\n\n![toktrack overview](assets/demo.gif)\n\n## 왜 toktrack인가?\n\n| 문제 | 해결책 |\n|------|--------|\n| 🗑️ **Claude Code 30일 후 데이터 삭제** — 비용 기록 사라짐 | 💾 **영구 캐시** — CLI가 파일을 삭제해도 기록 유지 |\n| 📊 **통합 뷰 없음** — CLI별로 데이터 분산 | 🎯 **원 대시보드** — Claude Code, Codex, Gemini, Qwen, OpenCode, PI Agent 통합 |\n| 🐌 **대용량 기록 재스캔이 느림** | ⚡ **캐시 시 ~0.04초** — 매 실행 즉시 |\n\n## 주요 기능\n\n- **데이터 보존** — 영구 캐시로 CLI가 세션 파일을 삭제한 뒤에도 비용 기록 유지\n- **멀티 CLI 지원** — Claude Code, Codex CLI, Gemini CLI, Qwen Code, OpenCode, PI Agent 한 곳에서\n- **TUI 대시보드** — 3개 탭 (Overview, Stats, Models), 일별/주별/월별 뷰\n- **CLI 명령어** — `daily`, `weekly`, `monthly`, `stats` (JSON 출력 지원)\n- **사용량 리포트** — 공유 가능한 텍스트 \u0026 SVG 영수증 (`toktrack report`)\n- **대용량에서도 빠름** — simd-json + rayon 병렬 파싱 (~3 GiB/s), 캐시 시 ~0.04초\n\n## 설치\n\n### npx (권장)\n\nRust 툴체인 불필요. 플랫폼에 맞는 바이너리를 자동으로 다운로드합니다.\n\n```bash\nnpx toktrack\n# 또는\nbunx toktrack\n```\n\n### Homebrew (macOS / Linux)\n\n```bash\nbrew tap mag123c/toktrack\nbrew install toktrack\n```\n\n### 소스에서 설치\n\n```bash\ncargo install --git https://github.com/mag123c/toktrack\n```\n\n### 미리 빌드된 바이너리\n\n[GitHub Releases](https://github.com/mag123c/toktrack/releases)에서 다운로드하세요.\n\n| 플랫폼 | 아키텍처 |\n|---------|----------|\n| macOS | x64, ARM64 |\n| Linux | x64, ARM64 |\n| Windows | x64 |\n\n## 빠른 시작\n\n```bash\n# TUI 대시보드 실행\nnpx toktrack\n\n# 오늘의 비용을 JSON으로 확인\nnpx toktrack daily --json\n\n# 월별 요약\nnpx toktrack monthly --json\n```\n\n## 사용법\n\n### TUI 모드 (기본)\n\n```bash\ntoktrack\n```\n\n### CLI 명령어\n\n```bash\n# 특정 탭으로 TUI 열기\ntoktrack daily     # Overview (일별 보기)\ntoktrack weekly    # Overview (주별 보기)\ntoktrack monthly   # Overview (월별 보기)\ntoktrack stats     # Stats 탭\n\n# JSON 출력 (스크립팅용)\ntoktrack daily --json\ntoktrack weekly --json\ntoktrack monthly --json\ntoktrack stats --json\n\n# 사용량 리포트 (공유용 영수증)\ntoktrack report              # 최근 7일 (텍스트)\ntoktrack report --month      # 최근 30일\ntoktrack report --days 14    # 최근 N일\ntoktrack report --svg        # 텍스트 + SVG 파일\n\n# 데이터 보존 감사 (디스크에 살아있음 vs 캐시에만 있음)\ntoktrack audit               # 소스별 커버리지 리포트\ntoktrack audit --json        # 머신 리더블\n```\n\n### 셸 통합\n\n오늘의 AI 지출을 프롬프트에 바로 표시 (명령마다 갱신):\n\n```\n~/projects/api  main  $12.40\n❯\n```\n\nzsh/bash/fish 몇 줄이면 됩니다 — **[셸 통합 가이드](docs/shell-integration.md)** 참고.\n\n### 키보드 단축키\n\n| 키 | 동작 |\n|-----|--------|\n| `1-4` | 탭 직접 전환 (Audit 포함) |\n| `Tab` / `Shift+Tab` | 다음 / 이전 탭 |\n| `j` / `k` 또는 `↑` / `↓` | 위 / 아래 스크롤 |\n| `Enter` | 모델 상세 팝업 열기 (Daily 탭) |\n| `d` / `w` / `m` | 일별 / 주별 / 월별 보기 (Daily 탭) |\n| `?` | 도움말 토글 |\n| `Ctrl+C` | 종료 |\n\n## 지원하는 AI CLI\n\n| CLI | 상태 | 데이터 위치 |\n|-----|--------|---------------|\n| Claude Code | ✅ | `~/.claude/projects/` |\n| Codex CLI | ✅ | `~/.codex/sessions/` |\n| Gemini CLI | ✅ | `~/.gemini/tmp/*/chats/` |\n| Qwen Code | ✅ | `~/.qwen/tmp/*/chats/` |\n| OpenCode | ✅ | `~/.local/share/opencode/storage/message/` |\n| PI Agent | ✅ | `~/.pi/agent/sessions/` |\n| Antigravity | ⚠️ 감지됨, 미지원 | `~/.gemini/antigravity-cli/` (로컬 파일에 토큰 사용량 없음) |\n\n\u003e 자체 비용을 기록하지 않는 소스(Gemini, Qwen, Codex, 최신 Claude 로그)의 비용은\n\u003e [LiteLLM](https://github.com/BerriAI/litellm) 가격으로 계산되며 `~` 마커(추정치)로 표시됩니다.\n\u003e 네트워크가 없을 때도 번들된 스냅샷으로 가격 계산이 동작합니다.\n\n### 환경 변수\n\n각 소스의 데이터 디렉터리는 상위 CLI가 쓰는 변수명으로 재지정할 수 있습니다:\n\n| 변수 | 소스 | 기본값 |\n|------|------|--------|\n| `CLAUDE_CONFIG_DIR` | Claude Code (루트) | `~/.claude` (+ `/projects`) |\n| `CODEX_HOME` | Codex CLI (루트) | `~/.codex` (+ `/sessions`) |\n| `GEMINI_CLI_HOME` | Gemini CLI (홈 루트) | `~` (+ `/.gemini/tmp`) |\n| `QWEN_HOME` | Qwen Code | `~/.qwen` (+ `/tmp`) |\n| `OPENCODE_DATA_DIR` / `XDG_DATA_HOME` | OpenCode | `~/.local/share/opencode` |\n| `PI_CODING_AGENT_SESSION_DIR` (이후 `PI_AGENT_DIR`) | PI Agent | `~/.pi/agent/sessions` |\n\n```bash\nexport CLAUDE_CONFIG_DIR=\"/path/to/.claude\"\n```\n\n커스텀 가격(`web_search`/`web_fetch` 요청당 단가 포함)은 `~/.toktrack/pricing.toml`에 설정할 수 있습니다.\n\n## 성능\n\n| 실행 | 시간 |\n|------|------|\n| 첫 실행 (콜드) | **~1.0초** |\n| 일상 사용 (캐시) | **~0.04초** |\n\n\u003e Apple Silicon 기준, 2,000+ JSONL 파일 (3.4 GB). 영구 캐시 덕분에 매 실행 시 현재 날짜만 재계산하고 지난 날짜는 캐시에서 바로 읽으므로, 기록이 아무리 커져도 일상 사용은 즉시 끝납니다.\n\u003e\n\u003e **왜 빠른가?** SIMD JSON 파싱 ([simd-json](https://github.com/simd-lite/simd-json)) + 병렬 처리 ([rayon](https://github.com/rayon-rs/rayon)) = 콜드 경로에서 ~3 GiB/s 처리량.\n\n## 데이터 보존\n\n\u003e **문제 상황:** Claude Code를 3개월간 사용하며 수십만 원을 썼습니다. 어느 날 총 지출을 확인하려는데 — 2개월 전 세션 파일이 이미 삭제되었습니다. 그 비용 데이터는 영원히 사라졌습니다.\n\n**toktrack이 이를 해결합니다.** 일별 비용 요약을 독립적으로 캐시하므로, CLI가 원본 파일을 삭제한 후에도 사용 기록이 보존됩니다.\n\n### CLI별 데이터 보존 정책 (숨겨진 위험)\n\n| CLI | 기본 보존 기간 | 정책 |\n|-----|----------------|------|\n| Claude Code | **30일** | `cleanupPeriodDays` (기본값: 30) |\n| Gemini CLI | 무제한 | opt-in `sessionRetention` |\n| Codex CLI | 무제한 | 용량 제한만 (`max_bytes`) |\n\n### toktrack 캐시 구조\n\n```\n~/.toktrack/\n├── cache/\n│   ├── claude-code_daily.json   # 일별 비용 요약\n│   ├── codex_daily.json\n│   ├── codex@devbox_daily.json\n│   ├── gemini_daily.json\n│   ├── opencode_daily.json\n│   └── pi-agent_daily.json\n├── remotes/\n│   └── devbox/codex/sessions/   # 동기화된 원격 Codex JSONL 스냅샷\n├── config.toml                  # 선택: 원격 소스 설정\n└── pricing.json                 # LiteLLM 가격 정보 (1시간 TTL)\n```\n\n각 `*_daily.json`의 지난 날짜 데이터는 **불변**입니다 — 한번 집계된 날의 결과는 수정되지 않습니다. 현재 날짜만 매 실행마다 재계산됩니다. 따라서 Claude Code가 30일 후 세션 파일을 삭제하더라도, 캐시에 비용 기록이 그대로 남습니다.\n\n### 무엇이 보존됐는지 직접 확인\n\n`toktrack audit`는 소스별·날짜별로 데이터가 아직 **live**(raw 세션 파일이 디스크에 존재)인지, **cache-only**(CLI가 raw를 삭제 — toktrack만 보유)인지, **missing**(데이터 없음 — 안 쓴 날이거나 toktrack이 보기 전에 사라진 날; 손실로 단정하지 않음)인지 보여줍니다.\n\n```\n$ toktrack audit\n\nData preservation audit (2026-06-08)\n\n  claude-code   2025-12-22 → 2026-06-08\n    live (raw on disk):         79 days\n    preserved (CLI deleted):    83 days\n    no data (unused or lost):    7 days\n  ...\n\n  ► 100 days of cost history preserved that your CLIs already deleted.\n```\n\n전체 일별 내역은 `toktrack audit --json`, 또는 TUI에서 **Audit** 탭(`4` 키)으로 시각적 커버리지 맵을 확인하세요.\n\n### Claude Code 자동 삭제 비활성화\n\n```json\n// ~/.claude/settings.json\n{\n  \"cleanupPeriodDays\": 9999999999\n}\n```\n\n### 캐시 초기화\n\n```bash\nrm -rf ~/.toktrack/cache/\n```\n\n다음 실행 시 사용 가능한 세션 데이터로부터 캐시를 재구축합니다.\n\n## 동작 방식\n\n![architecture](assets/architecture.png)\n\n**콜드 경로** (첫 실행): 전체 glob 스캔 → 병렬 SIMD 파싱 → 캐시 구축 → 집계.\n\n**웜 경로** (캐시 있음): 캐시된 요약 로드 → 최근 파일만 파싱 (어제 자정 mtime 필터) → 병합 → 집계.\n\n\u003e **Deep Dive:** [Node.js CLI를 Rust로 재작성 — 43초에서 1초로](https://mag1c.tistory.com/601) | [English](https://medium.com/@diehreo/i-rewrote-a-node-js-cli-in-rust-it-went-from-43s-to-1s-c13e38e7fe88)\n\n## 개발\n\n```bash\nmake check    # fmt + clippy + test (커밋 전 실행)\ncargo test    # 테스트 실행\ncargo bench   # 벤치마크 실행\n```\n\n## 로드맵\n\n현재 6개 CLI 지원 (Claude Code, Codex, Gemini, Qwen Code, OpenCode, PI Agent) — [지원하는 AI CLI](#지원하는-ai-cli) 참조. 예정: 실시간/번레이트 모니터링, MCP 서버 / statusline, 추가 CLI(Goose, Amp, Kimi, Copilot).\n\n## 기여하기\n\n이슈와 PR 환영합니다!\n\n```bash\nmake check  # PR 전 실행\n```\n\n## Star History\n\n\u003ca href=\"https://www.star-history.com/#mag123c/toktrack\u0026Date\"\u003e\n \u003cpicture\u003e\n   \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/svg?repos=mag123c/toktrack\u0026type=Date\u0026theme=dark\" /\u003e\n   \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/svg?repos=mag123c/toktrack\u0026type=Date\" /\u003e\n   \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/svg?repos=mag123c/toktrack\u0026type=Date\" /\u003e\n \u003c/picture\u003e\n\u003c/a\u003e\n\n## 라이선스\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmag123c%2Ftoktrack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmag123c%2Ftoktrack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmag123c%2Ftoktrack/lists"}