도움말

설치, 연결, 커스터마이즈, 문제 해결까지 — 5분이면 충분합니다.

설치

  1. 최신 DMG를 다운로드하세요.
  2. Token Run을 응용 프로그램으로 드래그한 뒤 실행하세요.
요구 사항: macOS 14.0 이상, Apple Silicon 또는 Intel.

첫 실행이 차단되면 시스템 설정 → 개인정보 보호 및 보안에서 그래도 열기를 클릭하세요.

제공자 연결

Token Run은 Claude Code, Codex CLI, GitHub Copilot CLI, Google Antigravity의 기존 세션으로 사용량을 읽어옵니다 — API 키는 필요 없어요. 여러 제공자를 동시에 켤 수 있고, 팝오버가 이를 합산해서 보여줍니다. 쿼터 카드는 Claude와 Codex에만 붙고, Copilot과 Antigravity는 러너 속도에만 반영됩니다.

Claude Code

팝오버를 열고 Connect Claude를 클릭한 뒤 OAuth를 승인하세요. 해제는 설정 → Claude Quota에서 할 수 있어요.

Codex CLI

Codex CLI에 로그인만 되어 있으면 Token Run이 자동으로 인식합니다. 끄려면 설정 → Providers에서 비활성화하세요.

GitHub Copilot CLI

Copilot CLI를 설치하고 한 번 실행하면 Token Run이 ~/.copilot/session-state를 자동으로 감지합니다. Copilot CLI 1.0.35 기준으로는 출력 토큰만 로그에 남고 입력·캐시 토큰은 아직 제공되지 않아, 표시되는 수치가 실제 사용량보다 과소 집계되고 쿼터 카드도 없어요. 끄려면 설정 → Providers에서 비활성화하세요.

Google Antigravity

Antigravity를 설치하세요. 대화 파일이 디스크에 암호화되어 저장되기 때문에 Token Run은 파일 크기 증가분을 활동 프록시로 사용합니다. 표시되는 토큰 수는 실제 사용량이 아니라 러너 속도를 움직이는 용도일 뿐이고, 쿼터 카드는 없어요. 끄려면 설정 → Providers에서 비활성화하세요.

  • 러너 스프라이트 — 분당 토큰 수에 따라 빨라집니다.
  • 토큰 수 — 오늘의 합계.
  • 쿼터 배터리 — 5시간 쿼터 잔량. Claude, Codex, 끔 중 선택.
  • 리셋 타이머 — 다음 5시간 윈도우까지의 카운트다운.

각 요소는 설정 → Menu bar에서 개별적으로 켜고 끌 수 있어요.

속도 단계

  • Resting(휴식) — 최근 활동 없음.
  • Walking(걷기) — 약 500 tok/분 미만.
  • Running(달리기) — 약 1,000 tok/분 이상.
  • Sprinting(질주) — 약 2,000 tok/분 이상.

캐릭터

설정 → Character에서 러너를 클릭해 전환하세요. 모든 캐릭터는 다크·라이트 메뉴 바 모두에 맞춰 렌더링됩니다.

커스텀 캐릭터

설정 → Character → + Add에서 직접 러너를 추가할 수 있어요. 가로 스프라이트 시트 PNG나 프레임 PNG 폴더를 넣고, 순서·fps를 조정한 뒤 저장하세요.

커뮤니티 백분위

이 기능을 켜면 팝오버에 다른 사용자와 비교한 주간 사용량 구간(예: 이번 주 상위 28%)이 표시됩니다. 익명 ID와 일일 토큰 총합만 전송되며, 계정 정보나 프롬프트 내용은 포함되지 않아요. 설정 → Share anonymized usage stats에서 언제든 끌 수 있습니다.

개인정보

  • 인증 정보는 각 CLI가 원래 저장하는 위치에 그대로 두며, 쿼터를 읽는 용도로만 사용합니다.
  • 프롬프트, 응답, 도구 호출, 파일 경로는 기기 밖으로 나가지 않습니다.
  • 토큰 수와 제공자별 세부 정보도 로컬에만 저장됩니다. 예외는 커뮤니티 백분위가 사용하는 일일 총합뿐이에요.

문제 해결

팝오버에 "Throttling requests…"가 표시돼요

쿼터 요청이 잠시 제한된 상태예요. 1~2분 내에 자동으로 갱신됩니다.

코딩 중인데도 러너가 멈춰 있어요

  • 사용 중인 제공자가 설정 → Providers에서 Installed 또는 Enabled 상태인지 확인하세요.
  • 분당 토큰 수가 걷기 임계값보다 낮을 수 있어요. 러너는 존재 여부가 아니라 처리량에 반응해요.
  • 여전히 0이라면 해당 제공자를 해제했다가 다시 연결해 보세요.

앱이 "손상되었다"거나 열리지 않아요

시스템 설정 → 개인정보 보호 및 보안에서 그래도 열기를 클릭하세요.

커스텀 캐릭터가 움직이지 않아요

  • 모든 프레임의 픽셀 크기가 같아야 합니다.
  • PNG를 사용하세요 — JPEG는 투명도가 사라집니다.
  • fps를 더 낮춰 보세요.

피드백

ryanstudio0429@gmail.com으로 문의주세요.