Token RPG

Claude Code에 쓴 토큰이 그대로 캐릭터가 되는 턴제 RPG.

실제로 코딩한 만큼 강해진다. 출력 토큰은 공격력, 캐시 재사용은 방어력, thinking 토큰은 치명타율이 된다. 버그 벌레부터 토큰 한도의 군주까지, 개발자의 적 15종이 던전 보스다.

$ token-rpg open
Lv.28 코드 술사 🧑‍💻  HP 775 ATK 90 DEF 40.0 CRIT 30.5%  던전 15개

설치

pipx install token-rpg
token-rpg open              # 집계 후 브라우저로 열기 (Ctrl+C 로 종료)

의존성은 없다. 표준 라이브러리만 쓴다. Python 3.9+ 만 있으면 macOS·리눅스·윈도우에서 같은 명령으로 돈다 (uv tool install token-rpg·pip install token-rpg 도 같다).

아직 안 나온 최신 커밋을 받고 싶으면 GitHub 주소를 그대로 쓴다.

pipx install git+https://github.com/YCYEOM/token-rpg

상주 앱

브라우저 탭을 띄워 두지 않고 늘 켜 두고 싶으면 OS 마다 상주 앱이 있다. 둘은 같은 일을 한다 — 저장 서버를 띄우고, 5분마다 사용량을 다시 집계하고, 아이콘을 누르면 게임을 연다. 저장 파일 하나를 브라우저와 함께 쓰므로 어느 쪽으로 해도 진행은 이어진다.

윈도우 — 알림 영역(트레이)

token-rpg-tray                  # 알림 영역에 상주 (콘솔 창 없음)
token-rpg-tray --startup on     # 로그인할 때 자동 실행

왼쪽 클릭이면 게임 창이 열리고(Edge 앱 모드 — 주소창 없이 팝오버에 가깝다. 없으면 기본 브라우저), 오른쪽 클릭이면 열기 · 지금 갱신 · 자동 실행 · 종료 메뉴가 나온다.

윈도우 트레이는 맥 메뉴 막대와 달리 아이콘 옆에 글자를 못 단다. 그래서 레벨과 배지가 툴팁 첫 줄(Lv.31 49% ⬆)로 간다 — 아이콘에 마우스를 올리면 보인다.

게임 데이터는 %LOCALAPPDATA%\token-rpg 에 둔다(token-rpg where 로 확인). Stop 훅은 cmd.exe 문법으로 등록된다.

macOS — 메뉴 막대

Token RPG.app은 메뉴 막대에 게임패드 아이콘으로 상주한다. 아이콘 옆에 레벨과 진행률(Lv.31 49%)이 뜨고, 마우스를 올리면 오늘 쓴 토큰·다음 레벨까지 남은 EXP를 보여준다. 아이콘을 누르면 팝오버 안에서 게임 전체를 그대로 할 수 있다.

배지: ⬆ 레벨이 올랐는데 아직 안 열어 봄 · ⛏ 원정이 가득 참 (수령해야 다시 쌓인다). 앱은 5분마다 사용량을 다시 집계하므로 Codex·Gemini 사용분도 반영된다.

받는 곳은 릴리스 페이지 — Token-RPG-macOS.dmg 를 받아 안에 든 Token RPG.app 을 Applications 로 드래그한다. 새 버전이 나오면 같은 자리에서 다시 받아 덮어쓰면 된다(메뉴 막대 앱은 자기 사본을 갈아치우지 못한다).

직접 빌드하려면 macOS Command Line Tools에서 다음을 실행한다.

zsh scripts/build-macos-app.sh
open dist-macos/Token-RPG-macOS.dmg

앱은 독립적인 Swift/AppKit UI이지만, 사용량 집계 로직은 번들에 든 token_rpg.py로 실행하므로 python3가 PATH에 있어야 한다. 앱이 읽는 것은 로컬 로그뿐이며, 데이터를 외부로 전송하지 않는다.

현재 생성되는 DMG는 서명·공증되지 않은 개발 빌드다. 다른 사람에게 배포하려면 Apple Developer ID로 서명하고 공증해야 Gatekeeper 경고 없이 열 수 있다.

자동 갱신

token-rpg install-hook      # Claude Code Stop 훅에 등록

이후 Claude Code가 응답을 마칠 때마다 스탯이 자동 갱신된다(백그라운드, 1초 미만). token-rpg uninstall-hook으로 되돌린다. ~/.claude/settings.json을 고치기 전에 항상 .bak 백업을 남긴다.

게임 구조

스탯 — 토큰 종류가 캐릭터 빌드를 정한다. 사용 패턴이 곧 개성이다.

던전 — 고정 보스 15종(버그 벌레 → 무한 루프 뱀 → … → 토큰 한도의 군주)이 한 층이다. 누구 PC에서든 같은 던전이고, 층마다 같은 보스가 지수로 강해져서 다시 나온다. 내 스탯은 토큰에 선형으로 크고 보스는 거듭제곱근으로 커서, 막힌 곳은 토큰을 더 쓰면 반드시 넘을 수 있다.

초월 — Lv.99 에서 레벨을 1로 되돌리고 다시 올린다. 레벨은 배분 포인트(2pt/레벨)를 주는데 99에서 막혀, 그 위로는 토큰을 아무리 써도 포인트가 안 늘었다. 이미 받은 포인트는 적립해 두고 레벨과 칭호만 처음으로 돌린다 — 초월 1회에 198pt 가 굳는다. 스탯 배분·혼·유물·클리어 기록은 건드리지 않는다. EXP 는 쓴 토큰이라 줄지 않으므로, 저장에 적힌 초월 횟수만큼 덜어내고 레벨을 다시 센다 (hero() 와 JS lvNow() 양쪽에 같은 식이 있고, selftest 가 표로 붙들어 둔다).

환생 — 클리어 기록과 스탯 배분을 버리고 혼을 얻는다. 혼으로 사는 영구 특성은 배율(×1.12/레벨)이라, 배분 포인트로는 따라갈 수 없는 층 벽을 넘게 해준다. 영구 특성은 일곱이다 — 힘·혼·벽·신속의 유산(ATK·HP·DEF·SPD ×1.12/레벨), 파괴의 유산(CDMG +5%p), 수확(얻는 혼 +3%), 각성(배분 포인트 +4).

상한이 있는 능력치는 영구 특성으로 두지 않는다 — 되팔 수 없는데 어느 레벨부터 값이 반으로 죽으면 그건 선택이 아니라 함정이다. 그래서 CRIT(상한 100%)은 토큰·배분 포인트·유물로만 오른다. 일곱 다 상한이 없어서 언제 사도 죽지 않고, 선택은 실수를 피하는 문제가 아니라 무엇을 먼저 사느냐의 문제가 된다.

신속의 유산 — SPD 는 원래 API 호출 수로만 정해져 손댈 수 없는 유일한 스탯이었다. 보스보다 느리면 선공을 내준다(던전 목록에 빨갛게 뜬다).

SPD 는 배분 포인트로도 올린다(+3/pt). 토큰만으로 얻는 SPD 는 13스테이지 보스의 1/9 수준이라, 배분 없이 특성만으로 뒤집으려면 20레벨(혼 6,475)이 든다 — 같은 혼이면 힘의 유산 ATK ×9.65 다. 그건 선택이 아니라 밑지는 장사다. 배분을 열어 두면 20pt + 신속 6레벨(혼 ~700)로 같은 자리를 뒤집는다. 대신 그 20pt 만큼 ATK 를 포기한다.

수확 — 지금 세게 할지, 다음 환생부터 더 많이 벌지. 3%/레벨은 시뮬레이션으로 고른 값이다. 더 올리면 층 벽이 무너진다 (6%면 3층 진입이 23회 → 19회). 환생 1회에는 기운 하나가 든다. 기운은 게임을 시작한 뒤 새로 쓴 토큰 100만마다 하나씩, 3개까지 쌓인다. 그래서 진행 속도가 실제 사용량에 묶인다 — 하루 150250만 쓰면 1층을 다 깨는 데 23일. 시작 전에 쓴 토큰은 세지 않는다.

원정 — 역대 최고로 깊이 간 스테이지를 자동 반복해 혼을 캔다. 최대 8시간까지 누적되고, 수령 이후 새로 쓴 토큰이 생산 배율이 된다(최대 3배). 환생해도 멈추지 않는다 — 기준이 이번 회차 진행이 아니라 역대 최고 기록이고, 쌓여 있던 미수령분도 그대로 남는다.

자동 도전 — 첫 환생 후 해금. 켜 두면 지금 능력치로 이길 수 있는 다음 스테이지를 1초에 하나씩 연출 없이 깬다. 더 못 오르면 멈추지 않고 이번 판 가장 깊은 스테이지를 계속 반복해 유물을 캔다. 옆 목록에서 역대 클리어한 스테이지를 고르면 거기까지만 오르고 그곳을 반복한다. 진 스테이지로는 능력치가 바뀔 때까지 다시 오르지 않는다. 켜 둔 채 환생하면 직전 배분을 그대로 다시 걸어 목표까지 알아서 올라간다.

미션 — 게임 안 행동이 아니라 실제 사용량으로 채워진다. 초기화 주기별로 나눠 보여준다 — 일일은 자정에, 주간은 월요일에 바뀐다.

일일은 오늘 토큰 T·2T·3T 세 단이고(AI 툴을 여럿 쓰면 "오늘 2개 이상"이 하나 더 붙는다), 주간은 5일 사용과 주간 토큰 5T다. 기준 T 는 지난 14일 평균의 절반이라 사용량에 맞춰진다. 연속 사용일마다 보상 +10%(최대 7일).

보상 총합은 하루치·한 주치로 고정되어 있고(DAY_BUDGET·WEEK_BUDGET, 단위는 최고 스테이지 보스 격파 몇 번분) 그날의 미션들이 가중치로 나눠 갖는다. 미션을 더 쪼개도 수입이 늘지 않는다. 쉬운 단은 적게 주므로 하루치를 다 받으려면 3단까지 가야 한다. 환생이 주 수입원으로 남도록 selftest 가 미션 주간 수입을 환생 수입과 견줘 상한을 지킨다.

유물 — 보스가 가끔 자기 유물을 떨어뜨린다(역대 첫 격파 30%, 재격파 0.5%). 반복 파밍으로 나온 중복은 혼으로 조금(1/10)만 바뀐다. 등급은 일반 60%·희귀 28%·영웅 10%·전설 2%이고 오를 때마다 효과가 두 배다 (ATK·HP·DEF·혼 +3/6/12/24%, CRIT +0.5/1/2/4%p). 보스마다 하나만 가지며 더 높은 등급이 나와야 바뀐다. 환생해도 남는다.

어떤 능력치가 붙을지는 보스마다 고정이다 — 무작위인 것은 등급뿐이다. ATK·HP·DEF·CRIT·혼 다섯 종을 보스 15종에 3개씩 나눠 층 앞뒤로 흩어 놨으니, 원하는 빌드에 맞춰 어디를 먼저 깰지 고르면 된다. 던전 목록과 유물 도감 양쪽에 무엇이 나올지 적혀 있다.

환생 보너스 — 환생할 때마다 얻는 혼(환생·원정·미션·유물 중복)이 영구히 +2%씩 는다. 10회면 +20%, 25회면 +50%. 혼 배수는 환생·유물·수확 셋이 곱해지므로, 캐릭터 카드 아래 얻는 혼 x1.34 (환생 +2% · 유물 +6% · 수확 +24%) 줄에 합쳐서 보여 준다.

시작점 — 설치한 날부터 센다. 이미 몇 달 치 로그가 쌓여 있으면 깔자마자 고레벨로 시작해 성장이 통째로 사라지기 때문이다. 처음 실행할 때 기준을 정하고 config.json 에 남긴다. 이미 쓰던 설치(스냅샷이나 저장이 있다)는 과거를 그대로 지킨다.

token-rpg since              # 지금 기준 보기
token-rpg since all          # 예전 기록까지 전부 세기
token-rpg since 2026-01-01   # 특정 날짜부터

세션 파일 단위로 거르므로 기준일을 걸친 세션 하나는 통째로 센다.

업데이트

새 버전이 있으면 게임 화면 맨 위에 알림이 뜬다. 업데이트 버튼을 누르면 깔린 방식 (uv tool·pipx)을 알아서 찾아 올린다. 끝나면 창을 다시 열면 된다.

token-rpg update        # 터미널에서도 같은 일을 한다

메뉴 막대 앱 안의 사본은 갈아치울 수 없어서, 그때는 버튼이 DMG 받기로 바뀐다. 받아서 Applications 에 덮어쓰면 된다.

버전 확인은 GitHub 릴리스 API 한 번이고, 파이썬 쪽에서 하고 결과를 6시간 재사용한다 (게임 페이지가 직접 바깥으로 나가지 않는다). 보내는 것은 버전 문자열뿐이고 사용량·로그는 어디로도 나가지 않는다. 끄려면 config.json 에 "updateCheck": false 를 넣는다.

여러 PC 합산

각 PC에서 token-rpg export를 돌리면 4KB짜리 스냅샷만 남는다. 스냅샷 폴더를 클라우드 동기화 폴더로 지정하면 모든 기기가 합쳐진다. 양쪽 OS 에서 같은 폴더를 가리키면 된다.

# macOS · 리눅스 (~/.zshrc 나 ~/.bashrc 에)
export TOKEN_RPG_SNAPSHOTS=~/Dropbox/token-rpg

# 윈도우 — setx 는 새로 여는 창부터 적용된다
setx TOKEN_RPG_SNAPSHOTS "$env:USERPROFILE\Dropbox\token-rpg"

지정한 뒤 각 PC 에서 token-rpg export 를 한 번 돌리면 그 폴더에 스냅샷이 생긴다. 기존 snapshots 폴더에 있던 파일은 새 폴더로 옮긴다 (token-rpg where 로 위치 확인).

사용량은 알아서 합쳐진다. PC 마다 <호스트이름>.json 을 따로 쓰고 합산할 때 전부 더하므로, 파일당 PC 하나라 충돌이 구조적으로 없다. 여러 PC 에서 동시에 코딩해도 된다.

게임 진행은 한 번에 한 PC 에서만 한다. game.save 는 파일 하나를 기기끼리 같이 쓴다. 한 PC 안에서는 브라우저 탭과 상주 앱이 rev 번호로 서로를 막아 주지만(오래된 창이 덮어쓰려 하면 거부하고 최신 저장을 불러온다), 다른 PC 끼리는 서로의 rev 를 볼 수 없다. 두 기기에서 동시에 켜 두면 동기화 서비스가 충돌 사본을 만들거나 늦게 쓴 쪽이 덮어쓴다. 한쪽에서 게임 창과 상주 앱을 닫고 동기화가 끝난 뒤 다른 쪽을 열면 된다.

명령

데이터

~/.claude/projects/**/*.jsonl의 usage 필드만 읽는다. 읽기 전용이고, 아무것도 밖으로 보내지 않는다. 게임 데이터는 ~/.local/share/token-rpg/(또는 $XDG_DATA_HOME)에 저장되고, 진행 상황은 브라우저 localStorage에 있다.

프로바이더

여러 AI 툴의 사용량을 한 캐릭터로 합산한다.

token-rpg providers                          # 목록과 스캔 위치
token-rpg scan add codex '~/backup/*/sessions'   # 로그가 기본 위치 밖일 때
token-rpg disable codex                      # 특정 프로바이더 끄기

Codex CLI는 cached_input_tokens·reasoning_output_tokens를 남겨 DEF·CRIT까지 그대로 대응된다. token_count 이벤트의 total_token_usage는 세션 누적이라 파일마다 마지막 값만 센다.

Gemini CLI는 텔레메트리 없이도 세션 로그(chats/session-*.jsonl)의 답변마다 tokens(input·output·cached·thoughts)를 남긴다. 답변 단위라 전부 더하고, cached는 DEF, thoughts는 CRIT로 대응된다.

웹에서 쓴 것은 잡히지 않는다. ChatGPT·Gemini 웹, Cursor, GitHub Copilot은 토큰 집계를 서버에서만 하고 로컬에 숫자를 남기지 않는다. CLI 툴을 설치해서 써야 기록이 생긴다.

새 툴을 붙이려면 PROVIDERS에 "파일 하나를 읽어 토큰 합계를 돌려주는 함수" 하나만 추가하면 된다. 또는 스냅샷 JSON을 직접 뱉어도 된다:

{"host": "내PC", "updated": "2026-09-10T00:00:00+00:00",
 "agg": {"input": 0, "output": 0, "cache_read": 0, "thinking": 0, "calls": 0},
 "projects": {"프로젝트명": 0}, "days": ["2026-09-10"]}

라이선스

MIT