token-rpg 0.5.0__tar.gz

token_rpg-0.5.0/.github/workflows/publish.yml

@@ -0,0 +1,43 @@
+name: Publish to PyPI
+
+# 릴리스를 발행할 때만 돈다. 토큰은 쓰지 않는다 —
+# PyPI가 GitHub의 OIDC 신원을 직접 검증한다 (Trusted Publishing).
+on:
+  release:
+    types: [published]
+  workflow_dispatch:        # 이미 나간 릴리스를 손으로 다시 올릴 때
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - name: 자체 검증
+        run: python token_rpg.py selftest
+      - name: 빌드
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  # PyPI 에 Trusted Publisher 를 등록하기 전에는 이 잡이 실패한다. 등록 전까지는
+  # 건너뛰게 둔다 — 릴리스는 그대로 나가고 CI 도 초록으로 남는다.
+  # 등록을 마치면 리포 Variables 에 PYPI_ENABLED=true 를 넣으면 그때부터 돈다.
+  publish:
+    needs: build
+    if: vars.PYPI_ENABLED == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write        # OIDC 토큰 발급 권한. 이것만 있으면 된다.
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

token_rpg-0.5.0/.github/workflows/test.yml

@@ -0,0 +1,25 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  selftest:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.9", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      # 집계·병합 로직과 난이도/환생 곡선을 검증한다.
+      # CI에는 Claude Code 기록이 없으므로 밸런스 검증은 자동으로 생략된다.
+      - run: python token_rpg.py selftest
+      # 트레이는 윈도우 전용이지만 순수 로직(툴팁·단위)은 어디서나 검증한다
+      - run: python token_rpg_tray.py --selftest
+      - run: pip install . && token-rpg --version && token-rpg where

token_rpg-0.5.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.DS_Store
+dist/
+build/
+*.egg-info/
+dist-macos/

token_rpg-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yeomyooncheol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

token_rpg-0.5.0/PKG-INFO

@@ -0,0 +1,301 @@
+Metadata-Version: 2.5
+Name: token-rpg
+Version: 0.5.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 git+https://github.com/YCYEOM/token-rpg
+token-rpg open              # 집계 후 브라우저로 열기 (Ctrl+C 로 종료)
+```
+
+의존성은 없다. 표준 라이브러리만 쓴다. Python 3.9+ 만 있으면 macOS·리눅스·윈도우에서
+같은 명령으로 돈다. 아직 PyPI 에 올리지 않아서 GitHub 주소로 받는다
+(`uv tool install git+https://github.com/YCYEOM/token-rpg` 도 같다).
+
+`git+` 형식은 git 이 PATH 에 있어야 한다. git 없이 받으려면 zip 주소를 쓴다.
+
+```bash
+pipx install https://github.com/YCYEOM/token-rpg/archive/refs/heads/main.zip
+```
+
+## 상주 앱
+
+브라우저 탭을 띄워 두지 않고 늘 켜 두고 싶으면 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 사용분도 반영된다.
+
+개발용으로 설치 파일을 만들려면 macOS Command Line Tools에서 다음을 실행한다.
+
+```bash
+zsh scripts/build-macos-app.sh
+open dist-macos/Token-RPG-macOS.dmg
+```
+
+DMG 안의 `Token RPG.app`을 `Applications`로 드래그하면 된다. 앱은 독립적인
+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에서든 같은 던전이고, 층마다 같은 보스가 지수로 강해져서 다시 나온다. 내 스탯은 토큰에 선형으로 크고 보스는 거듭제곱근으로 커서,
+막힌 곳은 토큰을 더 쓰면 반드시 넘을 수 있다.
+
+**환생** — 클리어 기록과 스탯 배분을 버리고 혼을 얻는다. 혼으로 사는 영구 특성은
+배율(×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` 를 볼 수 없다.
+두 기기에서 동시에 켜 두면 동기화 서비스가 충돌 사본을 만들거나 늦게 쓴 쪽이 덮어쓴다.
+한쪽에서 게임 창과 상주 앱을 닫고 동기화가 끝난 뒤 다른 쪽을 열면 된다.
+
+## 명령
+
+| 명령 | 하는 일 |
+|---|---|
+| `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