Metadata-Version: 2.5
Name: token-rpg
Version: 0.11.0
Summary: Claude Code 토큰 사용량으로 성장하는 턴제 RPG
License-Expression: MIT
License-File: LICENSE
Keywords: claude,claude-code,cli,idle-game,rpg,token-usage
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Games/Entertainment :: Role-Playing
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# Token RPG

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

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

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

## 설치

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

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

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

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

## 상주 앱

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

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

```powershell
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 사용분도 반영된다.

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

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

```bash
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 경고 없이 열 수 있다.

## 자동 갱신

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

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

## 게임 구조

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

| 스탯 | 출처 |
|---|---|
| ATK | 출력 토큰 |
| DEF | 캐시 읽기 (재사용 효율이 곧 방어력) |
| CRIT | thinking 토큰 (토큰만으로 최대 50%, 전체 상한 100% — 넘친 만큼 CDMG로) |
| CDMG | 치명타 피해. 기본 200%, 배분 +1%p/pt, 특성 '파괴의 유산' +5%p/lv |
| SPD | API 호출 수 (+ 배분 포인트) |
| EXP | 입력 + 캐시 생성 + 출력 |

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

**극초반은 완만하다 (v0.11.0)** — 예전엔 1스테이지 보스를 잡는 데 누적 200만 토큰이
필요했다. 갓 깐 Lv.1 은 ATK 가 0 인데 보스 DEF 가 8 이라 데미지가 한 점도 안 들어가,
시작조차 못 하고 꺾이는 구간이었다. 이제 6스테이지까지 보스 능력치를 눌러 두고 거기서
원래 곡선에 합류한다 — **토큰 0 으로도 1스테이지는 깬다.** 레벨 곡선도 저렙만 완만해져
Lv.2 가 9배(5,460 EXP), Lv.10 이 1.8배 빠르다. Lv.32 에서 1.18배, Lv.70 위로는 예전과
같고 **Lv.99 총량(=초월 비용)은 그대로**다 — 손본 건 극초반뿐이다.

**초월** — 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개까지 쌓인다. 그래서 진행 속도가 실제 사용량에 묶인다 — 하루 150~250만 쓰면
1층을 다 깨는 데 2~3일. 시작 전에 쓴 토큰은 세지 않는다.

**원정** — 역대 최고로 깊이 간 스테이지를 자동 반복해 혼을 캔다. 최대 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개씩 나눠 층 앞뒤로 흩어 놨으니, 원하는 빌드에 맞춰 어디를 먼저
깰지 고르면 된다. 던전 목록과 유물 도감 양쪽에 무엇이 나올지 적혀 있다.

| | 보스 |
|---|---|
| ATK | 버그 벌레 · 스파게티 크라켄 · 스택 오버플로 히드라 |
| HP | 레거시 전갈 · 메모리 누수 슬라임 · 프로덕션 장애 드래곤 |
| DEF | 널 포인터 박쥐 · 데드락 골렘 · 기술 부채 리치 |
| CRIT | 무한 루프 뱀 · 머지 충돌 도깨비 · 레이스 컨디션 유령 |
| 혼 | 좀비 프로세스 · 의존성 지옥 악마 · 토큰 한도의 군주 |

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

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

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

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

## 업데이트

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

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

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

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

## 여러 PC 합산

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

```bash
# macOS · 리눅스 (~/.zshrc 나 ~/.bashrc 에)
export TOKEN_RPG_SNAPSHOTS=~/Dropbox/token-rpg
```
```powershell
# 윈도우 — 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` 를 볼 수 없다.
두 기기에서 동시에 켜 두면 동기화 서비스가 충돌 사본을 만들거나 늦게 쓴 쪽이 덮어쓴다.
한쪽에서 게임 창과 상주 앱을 닫고 동기화가 끝난 뒤 다른 쪽을 열면 된다.

**진행 저장은 봉인해서 적는다.** `game.save` 는 v0.10.0 부터 `base64(JSON).서명` 한 줄이라
텍스트 편집기로 열어 혼·환생·배분을 고칠 수 없다. 서명이 맞지 않으면 불러오지 않는다.
쓰던 설치는 처음 갱신할 때 자동으로 봉인되니 따로 할 일은 없다 — **다만 이 파일을 같이 쓰는
설치본은 전부 v0.10.0 이상이어야 한다.** 한 PC 안에서도 설치본이 여러 개일 수 있으니
(`uv tool`·`pip`·맥 앱 번들) `token-rpg update` 를 각각 돌릴 것.

스냅샷(`snapshots/*.json`)도 봉인해서 쓰지만 **평문도 받아 준다.** 옛 설치본의 훅이 평문으로
덮어쓰는 일이 흔한데 거기서 거부하면 그 PC 토큰이 0 이 되기 때문이다. 스냅샷은 매번 진짜
로그에서 다시 만들어지므로 손대도 다음 갱신에 덮어써진다.

열쇠가 소스 안에 있어 작정하면 위조할 수 있다. 막는 대상은 "파일 열어서 0 하나 더 붙이기"다.

## 명령

| 명령 | 하는 일 |
|---|---|
| `token-rpg` / `build` | 사용량 재집계 후 `game.html` 갱신 |
| `open` | 갱신 후 로컬 서버(`127.0.0.1:8765`)로 브라우저에서 열기. Ctrl+C로 종료 |
| `serve` | 게임과 저장만 제공 (메뉴 막대 앱이 띄운다) |
| `export` | 이 PC의 스냅샷만 갱신 |
| `balance` | 난이도·환생 곡선 표 출력 |
| `selftest` | 집계·병합·밸런스 자체 검증 |
| `where` | 데이터 위치 출력 |
| `update` | 새 버전 확인 후 업그레이드 |
| `since [all\|now\|YYYY-MM-DD]` | 언제부터의 토큰을 셀지 보기/바꾸기 |
| `install-hook` / `uninstall-hook` | 자동 갱신 등록/해제 |

## 데이터

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

## 프로바이더

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

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

| 프로바이더 | 기본 위치 | 상태 |
|---|---|---|
| `claude-code` | `~/.claude/projects` | 검증됨 |
| `codex` | `~/.codex/sessions` | 검증됨 (codex cli 0.153.4) |
| `gemini` | `~/.gemini/tmp` | 검증됨 (gemini cli 0.59.0) |

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을 직접 뱉어도 된다:

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