Skip to content

Turn a ~$5 AliExpress clock into a physical AI usage dashboard (Claude, Codex, multi-account). No firmware flashing.

Initial scaffold: mock usage daemon, provider interface, plan notes

click6067-ship-itdcc79bb81883
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..421c27d
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,3 @@
+/vendor/
+__pycache__/
+*.pyc
diff --git a/BRIEF.md b/BRIEF.md
new file mode 100644
index 0000000..e90b5cf
--- /dev/null
+++ b/BRIEF.md
@@ -0,0 +1,51 @@
+# TokenTV — $5 AliExpress 시계를 AI 사용량 물리 대시보드로
+
+## 목표 (왜)
+GitHub 스타/레딧 바이럴이 목적. 훅은 "6천원짜리 알리 날씨시계가 Claude/Codex 사용량을 보여준다".
+사용자는 이미 기기를 갖고 있고 (`~/ghq/.../token-tv`가 작업 디렉터리), 과거에 한 번 비슷한 걸 만들어봤음
+(smalltv-mod 포크 + ai-usage-taskbar-widget에서 쿼터 받아 푸시) — 다만 디자인(AI생성 이미지 기반)이 별로였음.
+
+## 하드웨어 현황 (중요: 아직 준비 안 됨)
+- GeekMagic SmallTV 계열 시계, 현재 Mini PC에 USB로 전원만 연결된 상태.
+- 아직 어떤 WiFi에도 붙어있지 않음 (사용자가 폰으로 핫스팟→집 WiFi 전환 작업을 곧 할 예정).
+- **지금 단계에서는 기기 IP/실물 테스트가 불가능** — 그 전까지 할 수 있는 소프트웨어 작업만 먼저 진행.
+- 기기가 WiFi에 붙으면 사용자가 IP를 알려줄 것 — 그 전까지는 이 작업을 TODO로 남겨두고 블로킹하지 말 것.
+
+## 참고 레포 (반드시 먼저 clone해서 실제 코드 읽고 시작할 것 — 추측으로 짜지 말 것)
+1. https://github.com/giovi321/smalltv-mod — 펌웨어 베이스 (ESP8266/SmallTV-ultra/ESP32-C2/ESP32 지원,
+ WiFi OTA 지원, Claude usage meter 모드 이미 있음). 이 레포의 구조·OTA 업데이트 절차·기존 Claude 모드
+ 코드를 먼저 읽고, 거기에 얹는 방식으로 접근.
+2. https://github.com/sallyHADEV/ai-usage-taskbar-widget — 멀티계정 인증 + 사용량 조회 로직 참고용.
+ 여기서 Claude/Codex 등 provider별 사용량을 어떻게 긁어오는지 확인하고 재사용 가능한 부분 파악.
+
+## 아키텍처 (이전 기획 논의에서 정리된 방향)
+```
+PC(Mini) 데몬 ─(provider adapter: claude/codex/...)→ normalized JSON ─(LAN, HTTP)→ SmallTV(펌웨어)
+```
+- API 키/세션 토큰은 기기(ESP)에 절대 넣지 않는다 — Mini의 데몬에만 둔다.
+- 데몬은 provider별로 플러그인 구조 (`providers/claude.ts`, `providers/codex.ts` 등 — 언어는 기존 참고
+ 레포들과 맞춰서 판단, 억지로 TS 고집할 필요 없음).
+- 기기 쪽은 "dumb display"로 유지 — 가능하면 smalltv-mod의 기존 OTA/웹UI 인터페이스를 그대로 활용하고
+ 새 커스텀 펌웨어 빌드를 최소화 (논의에서 나온 "무플래싱에 가까운" 방향과, 사용자가 이미 자체 포크로
+ 진행한 "펌웨어 뜯어고침" 방향 중, smalltv-mod 코드를 실제로 읽어본 뒤 더 간단한 쪽으로 판단해도 됨 —
+ 단, 이 판단 근거를 나중에 설명할 수 있게 남겨둘 것).
+- 다계정 지원 필수 (예: Claude personal/work 등 alias로 구분해서 화면에 표시).
+
+## 지금 할 일 (기기 연결 전에 가능한 범위)
+1. `smalltv-mod`, `ai-usage-taskbar-widget` 를 `vendor/` 또는 `reference/` 하위에 clone해서 코드 구조 파악
+ (이 디렉터리는 git submodule이 아니라 그냥 참고용 — .gitignore 처리하거나 별도 clone 경로 사용).
+2. 두 레포를 분석한 결과를 바탕으로, 이 프로젝트의 구체적 구현 계획(데몬 언어/구조, 펌웨어에 얹을 방식,
+ provider 플러그인 인터페이스)을 `PLAN.md`로 작성. 추측 금지 — 읽은 코드 기반으로만 작성.
+3. Mini 데몬 쪽 스캐폴딩(디렉터리 구조, provider interface, mock JSON 응답)까지는 기기 없이도 구현/테스트 가능 —
+ 거기까지 진행.
+4. 기기 플래싱/실제 통신이 필요한 부분은 명확히 TODO로 표시하고 멈출 것 — 기기 IP를 받기 전까지는
+ 추측으로 "이 IP일 것이다" 하고 진행하지 말 것.
+
+## 하지 말 것
+- 존재하지 않는 API/엔드포인트를 추측해서 구현하지 말 것 — 반드시 clone한 레포의 실제 코드를 읽고 확인.
+- 기기에 API 키/크리덴셜 저장하는 구조로 설계하지 말 것.
+- 커밋/푸시는 아직 하지 말 것 (로컬 작업만, 사용자 확인 후 리모트 결정).
+
+## 보고
+작업 끝나면 무엇을 clone했는지, PLAN.md에 뭘 썼는지, 스캐폴딩 범위, 남은 블로커(기기 연결 대기 등)를
+간결하게 정리해서 알려줘.
diff --git a/PLAN.md b/PLAN.md
new file mode 100644
index 0000000..4da4bb1
--- /dev/null
+++ b/PLAN.md
@@ -0,0 +1,41 @@
+# TokenTV 구현 계획
+
+## 근거와 현재 결정
+
+참고 코드는 `vendor/`에 별도 clone했고 Git 추적에서 제외했다.
+
+| 저장소 | 확인한 코드 | 결론 |
+| --- | --- | --- |
+| `giovi321/smalltv-mod` @ `32d4832` | `src/features/usage/UsageClient.cpp:30`, `src/WebPortal.cpp:370`, `src/features/theme/ThemeDataClient.cpp:91`, `docs/src/content/docs/features/themes.md:163` | 기본 Claude 모드는 `{s,sr,w,wr,st,ok}`의 **단일** 사용량만 처리한다. `/api/usage` POST도 같은 단일 형식이다. 다계정은 테마의 JSON 데이터 바인딩으로 구현한다. |
+| `giovi321/smalltv-mod` @ `32d4832` | `docs/src/content/docs/getting-started/flashing.md:14`, `src/WebPortal.cpp:513` | 설치 방법은 보드에 따라 다르다. ESP8266 일부와 Pro는 stock 웹 OTA가 가능하지만 ESP32-C2는 초기 설치에 USB 직렬 플래시가 필요하다. 현재 보드 미확인. |
+| `sallyHADEV/ai-usage-taskbar-widget` @ `ac348ab` | `src/services/claude-local-client.ts:14`, `src/services/codex-app-server-client.ts:273`, `src/services/account-store.ts:32`, `src/services/usage-push.ts:4` | Claude는 로컬 CLI 세션 파일과 usage 조회를, Codex는 app-server의 `account/read`와 `account/rateLimits/read`를 사용한다. 위젯의 계정 목록은 있으나 Claude 로컬 소스가 전역 자격 증명을 공유하므로 personal/work의 독립 사용량을 이 코드만으로 보장하지 못한다. 위젯의 push 형식(`screen`, `items`)도 smalltv-mod의 `/api/usage` 형식과 호환되지 않는다. |
+
+따라서 첫 화면 구현은 **smalltv-mod 정규 이미지 + `.stheme` 사용자 테마 + Mini HTTP 데몬**으로 한다. 테마는 펌웨어 재빌드 없이 URL에서 JSON 필드를 읽는다. Claude 기본 모드는 단일 계정 대안으로만 남긴다. 모델 확인 전에는 이미지와 설치 절차를 확정하지 않는다.
+
+## 데이터 흐름
+
+1. Mini 데몬에 `key`, `alias`, `provider`, 추후 `source`를 가진 계정을 등록한다. `key`는 테마 URL에 쓰는 안정적인 영숫자 ID이고 `alias`는 화면 표기명이다. 서로 다른 계정은 서로 다른 인증 소스를 가져야 한다.
+2. provider adapter `fetch(account) -> Usage`가 세션/주간 사용률, 리셋까지 남은 분, 상태를 반환한다. 값이 없으면 `null`로 표현한다. 실패를 0% 사용으로 위장하지 않는다.
+3. `GET /snapshot/<key>`는 한 계정의 작은 JSON을 제공한다. 테마는 계정당 data source 하나를 두고 `alias`, `status`, `session_percent`, `weekly_percent` 등의 scalar path를 바인딩한다. 전체 목록 `GET /snapshot`은 로컬 점검용이다.
+4. smalltv-mod 테마의 제한은 source 최대 4개, source당 field 최대 8개, 응답 최대 2 KiB, 최소 갱신 간격 10초다 (`docs/src/content/docs/features/themes.md:163`). 그러므로 첫 테마는 최대 4개 계정을 한 화면에 고정 배치한다. 초과 계정의 페이지 전환은 후속 설계가 필요하다.
+
+현재 스캐폴드는 Python 3 표준 라이브러리로 작성했다. Mini에서 의존성 없이 실행 가능하고, HTTP 서버와 provider 인터페이스를 빠르게 검증할 수 있다. 위젯의 Electron/Windows 전용 코드를 그대로 가져오지 않는다. 실데이터 adapter는 소스별 동작과 현재 인증 방식 확인 후 별도 구현한다.
+
+## 단계
+
+1. **지금: 완료** — 데몬 모듈, `Provider` 인터페이스, 구별되는 3개 mock 계정, `/snapshot` 및 `/snapshot/<key>` JSON 응답, 로컬 테스트. mock 값은 `status: "mock"`으로 명시한다. 인증 정보는 응답에 없다. 기본 바인드는 `127.0.0.1`이다.
+2. **Mini 실데이터** — Claude/Codex adapter를 추가한다. 소스별 계정 구분 방법부터 검증한다. 다른 OS 계정/별도 세션 경로 등이 필요할 수 있으나 지금은 미검증이다. 실제 인증 파일의 원문을 로그/응답/저장소에 싣지 않는다. provider 조회 실패와 오래된 데이터를 `error`/`stale`로 노출하고 갱신 시각을 보존한다. 현재 API 동작은 구현 시 재확인한다.
+3. **화면** — `smalltv-mod`의 `examples/themes/live-status/theme.json` 형식을 토대로 240×240 테마를 만든다. 계정 alias를 문자로 표시하고 사용률을 수치와 막대로 함께 표시한다. `tools/smalltv_theme.py validate`와 오프라인 preview로 디자인을 확인한다. URL은 확인된 Mini LAN 주소로 구성한다.
+4. **기기 연결 후 TODO** — WiFi 연결 및 IP 확보, 실제 MCU/모델 확인, stock 펌웨어 백업 가능 여부와 설치 경로 확인, 해당 모델에 맞는 정규 이미지 설치, 테마 업로드, 기기에서 Mini URL 접근과 JSON 렌더 실측. ESP32-C2라면 초기 설치는 OTA가 아니라 USB 직렬 플래시 경로다. 실제 IP와 모델을 받기 전에는 플래싱하지 않는다.
+
+## 판정 기준
+
+- mock 단계: 서로 다른 3개 alias가 서로 다른 키로 조회되고, JSON에 토큰/자격 증명이 없고, 응답이 2 KiB 이하다.
+- 실데이터 단계: 같은 provider의 두 계정이 실제로 서로 다른 세션에서 조회됨을 확인한다. 검증 전에는 다계정 실사용 완료로 표시하지 않는다.
+- 기기 단계: 실제 240×240 화면에 alias와 사용률이 구별되어 렌더되고, 실패/오래된 값이 정상값으로 오인되지 않는다.
+
+## 미해결 사항
+
+- 기기 IP, 정확한 보드와 현재 firmware, Mini에서 접근 가능한 LAN 주소가 아직 없다.
+- 실계정별 Claude/Codex 인증 소스는 아직 검증하지 않았다. reference 위젯만으로는 다계정 독립 조회가 성립하지 않는다.
+- 테마 JSON URL은 LAN HTTP다. 사용량 수치만 노출하며 Mini의 자격 증명은 서버 안에 둔다. LAN 공개 시 접근 제어 방식은 실제 네트워크 확인 후 결정한다.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d2c7bd2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,26 @@
+# TokenTV
+
+Mini 데몬 스캐폴드와 구현 계획은 [PLAN.md](PLAN.md)에 있다. 현재 응답은 **mock 데이터**이며 실제 계정 사용량을 조회하지 않는다.
+
+Python 3.10+에서 실행:
+
+```bash
+python3 -m token_tv.app
+curl http://127.0.0.1:8787/snapshot
+curl http://127.0.0.1:8787/snapshot/claude_work
+python3 -m unittest discover -s tests
+```
+
+기기에서 접근할 때는 Mini의 실제 LAN 인터페이스 주소로 바인드해야 한다. 확인한 주소를 `--host`에 넣어 실행한다. 기기 IP와 보드 모델 확인 전까지 테마 설치와 통신 검증은 보류한다.
+
+```bash
+python3 -m token_tv.app --host <mini-lan-ip> --port 8787
+```
+
+응답의 `status: "mock"`은 예시 수치임을 뜻한다. `/snapshot/<key>`는 smalltv-mod 테마 JSON source용이며, `/snapshot`은 전체 계정 점검용이다. 데몬에 자격 증명을 등록하거나 기기에 전송하는 기능은 아직 없다.
+
+`/snapshot/claude_work` 응답 예시:
+
+```json
+{"alias":"Claude work","provider":"claude","status":"mock","session_percent":61,"session_reset_minutes":80,"weekly_percent":22,"weekly_reset_minutes":2400}
+```
diff --git a/tests/test_app.py b/tests/test_app.py
new file mode 100644
index 0000000..7063cb9
--- /dev/null
+++ b/tests/test_app.py
@@ -0,0 +1,41 @@
+import json
+import threading
+import unittest
+from urllib.request import urlopen
+
+from http.server import ThreadingHTTPServer
+
+from token_tv.app import MOCK_ACCOUNTS, make_handler
+from token_tv.providers.mock import MockProvider
+
+
+class SnapshotTests(unittest.TestCase):
+ def test_snapshot_exposes_distinct_aliases_as_theme_paths(self):
+ server = ThreadingHTTPServer(("127.0.0.1", 0), make_handler(MOCK_ACCOUNTS, {
+ "claude": MockProvider(),
+ "codex": MockProvider(),
+ }))
+ thread = threading.Thread(target=server.serve_forever)
+ thread.start()
+ try:
+ with urlopen(f"http://127.0.0.1:{server.server_port}/snapshot") as response:
+ payload = response.read()
+ self.assertLessEqual(len(payload), 2048)
+ self.assertEqual(response.headers["Content-Type"], "application/json; charset=utf-8")
+ data = json.loads(payload)
+ self.assertEqual(data["schema"], 1)
+ self.assertEqual(set(data["accounts"]), {"claude_personal", "claude_work", "codex_personal"})
+ self.assertEqual(data["accounts"]["claude_work"]["alias"], "Claude work")
+ self.assertEqual(data["accounts"]["claude_work"]["status"], "mock")
+ with urlopen(f"http://127.0.0.1:{server.server_port}/snapshot/claude_work") as response:
+ account = json.load(response)
+ self.assertEqual(account["session_percent"], 61)
+ self.assertEqual(account["alias"], "Claude work")
+ finally:
+ server.shutdown()
+ server.server_close()
+ thread.join()
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/token_tv/__init__.py b/token_tv/__init__.py
new file mode 100644
index 0000000..cf771ca
--- /dev/null
+++ b/token_tv/__init__.py
@@ -0,0 +1 @@
+"""TokenTV Mini daemon scaffold."""
diff --git a/token_tv/app.py b/token_tv/app.py
new file mode 100644
index 0000000..122b97d
--- /dev/null
+++ b/token_tv/app.py
@@ -0,0 +1,75 @@
+import argparse
+import json
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+from token_tv.providers.base import Account, Provider, Usage
+from token_tv.providers.mock import MockProvider
+
+
+MOCK_ACCOUNTS = (
+ Account("claude_personal", "Claude personal", "claude"),
+ Account("claude_work", "Claude work", "claude"),
+ Account("codex_personal", "Codex personal", "codex"),
+)
+
+
+def build_snapshot(accounts: tuple[Account, ...], providers: dict[str, Provider]) -> dict:
+ result = {}
+ for account in accounts:
+ try:
+ usage = providers[account.provider].fetch(account)
+ except (KeyError, OSError, ValueError):
+ usage = Usage("error", None, None, None, None)
+ result[account.key] = {
+ "alias": account.alias,
+ "provider": account.provider,
+ "status": usage.status,
+ "session_percent": usage.session_percent,
+ "session_reset_minutes": usage.session_reset_minutes,
+ "weekly_percent": usage.weekly_percent,
+ "weekly_reset_minutes": usage.weekly_reset_minutes,
+ }
+ return {"schema": 1, "accounts": result}
+
+
+def make_handler(accounts: tuple[Account, ...], providers: dict[str, Provider]):
+ class Handler(BaseHTTPRequestHandler):
+ def do_GET(self):
+ if self.path == "/snapshot":
+ data = build_snapshot(accounts, providers)
+ elif self.path.startswith("/snapshot/"):
+ key = self.path.removeprefix("/snapshot/")
+ account = next((item for item in accounts if item.key == key), None)
+ if account is None:
+ self.send_error(404)
+ return
+ data = build_snapshot((account,), providers)["accounts"][key]
+ else:
+ self.send_error(404)
+ return
+ body = json.dumps(data, separators=(",", ":")).encode()
+ self.send_response(200)
+ self.send_header("Content-Type", "application/json; charset=utf-8")
+ self.send_header("Content-Length", str(len(body)))
+ self.send_header("Cache-Control", "no-store")
+ self.end_headers()
+ self.wfile.write(body)
+
+ return Handler
+
+
+def main():
+ parser = argparse.ArgumentParser(description="TokenTV mock usage daemon")
+ parser.add_argument("--host", default="127.0.0.1")
+ parser.add_argument("--port", type=int, default=8787)
+ args = parser.parse_args()
+ with ThreadingHTTPServer((args.host, args.port), make_handler(MOCK_ACCOUNTS, {
+ "claude": MockProvider(),
+ "codex": MockProvider(),
+ })) as server:
+ print(f"TokenTV mock listening at http://{args.host}:{server.server_port}/snapshot", flush=True)
+ server.serve_forever()
+
+
+if __name__ == "__main__":
+ main()
diff --git a/token_tv/providers/__init__.py b/token_tv/providers/__init__.py
new file mode 100644
index 0000000..31544c5
--- /dev/null
+++ b/token_tv/providers/__init__.py
@@ -0,0 +1 @@
+"""Usage provider adapters."""
diff --git a/token_tv/providers/base.py b/token_tv/providers/base.py
new file mode 100644
index 0000000..1942e70
--- /dev/null
+++ b/token_tv/providers/base.py
@@ -0,0 +1,23 @@
+from dataclasses import dataclass
+from typing import Protocol
+
+
+@dataclass(frozen=True)
+class Account:
+ key: str
+ alias: str
+ provider: str
+
+
+@dataclass(frozen=True)
+class Usage:
+ status: str
+ session_percent: float | None
+ session_reset_minutes: int | None
+ weekly_percent: float | None
+ weekly_reset_minutes: int | None
+
+
+class Provider(Protocol):
+ def fetch(self, account: Account) -> Usage:
+ """Return usage for one configured account without exposing credentials."""
diff --git a/token_tv/providers/mock.py b/token_tv/providers/mock.py
new file mode 100644
index 0000000..447cd78
--- /dev/null
+++ b/token_tv/providers/mock.py
@@ -0,0 +1,11 @@
+from token_tv.providers.base import Account, Usage
+
+
+class MockProvider:
+ def fetch(self, account: Account) -> Usage:
+ samples = {
+ "claude_personal": Usage("mock", 29, 142, 4, 9876),
+ "claude_work": Usage("mock", 61, 80, 22, 2400),
+ "codex_personal": Usage("mock", 17, 95, 38, 5100),
+ }
+ return samples[account.key]