development.md

RunTime 개발 기록

RunTime(옛 이름 TokenCat)을 만들면서 정한 설계, 잰 숫자, 겪은 문제를 모았다. 사용법은 README에 있다.

• 기간: 2026.07부터. 이틀 동안 기획안 작성, M0~M3, v1.1, 오픈소스 배포까지 했고 이후 러너·미니게임·순위·업데이트를 더했다.
• 스택: Swift 5.9, SwiftUI + AppKit(NSStatusItem), SPM, macOS 13+
• UX 참고: RunCat(메뉴바 러너와 다크 팝오버), 냥캣(무지개 꼬리)

1. 목표와 하지 않은 것

• 코딩하다가 시선을 옮기지 않고도 지금 토큰을 얼마나 쓰고 있는지 러너 속도로 느끼게 한다.
• 클릭 한 번으로 5시간 세션 사용량, 주간 사용량, 오늘 토큰과 추정 비용, 초기화 시각을 본다.
• 한도가 가까워지면(80%/95%) 러너 모습과 macOS 알림으로 미리 알린다.
• 하지 않은 것: Windows/Linux 지원, 팀 단위 집계, 과거 통계 차트, App Store 배포

2. 핵심 성과 요약

항목	결과
집계 정확도	검증 도구 ccusage blocks와 동시점 대조 오차 0.00% (샌드위치 검증: 측정→대조→측정)
공식 게이지	비문서화 OAuth usage 엔드포인트 실측 연동 — 게이지는 공식 값만 표시해 /usage와 동일 값
성능	유휴 CPU 0.05%, 30fps 질주 0.5% (예산 0.5%), 메모리 17~21MB (예산 50MB) — 실측
품질	단위 테스트 102개 (swift-testing, ./scripts/test.sh) — 파서·중복제거·블록·게이지·알림·틱 판단, 게임 규칙
데이터 검증	실물 JSONL 1,432건 분석 → 중복 기록(최대 6줄) 발견, 중복제거 미적용 시 2.9배 과대집계 확인
배포	git clone + ./install.sh 3줄 설치 (로컬 빌드 → Gatekeeper 차단 없음), MIT 오픈소스

3. 데이터 소스 설계 — 실물 우선 검증

원칙: 문서·추측보다 실물 데이터 우선. 구현 첫날(M0)에 스파이크로 재검증했다.

항목	내용
원천 데이터	~/.claude/projects/**/*.jsonl — Claude Code가 세션별 대화·usage 기록. assistant 메시지에 message.usage(input/output/cache_creation/cache_read tokens), timestamp, message.model, requestId
검증된 선례	ccusage(CLI)가 동일 JSONL을 파싱해 일별/세션/5시간 블록 리포트 제공 — 파싱·중복제거·단가 로직 참조
5시간 블록	첫 활동 시각을 UTC 정시로 내림(floor)한 시점부터 5시간 창 (ccusage와 동일 규칙)
주간 사용량	공식 리셋 시각을 알면 그 주간 창, 모르면 최근 7일 롤링 합계 (모델 비중 표시용)
공식 사용량 % (게이지)	비문서화 OAuth usage 엔드포인트 — Claude Code가 로컬에 저장한 OAuth 토큰으로 조회하면 /usage와 동일한 세션·주간 %와 리셋 시각 응답. 웹/데스크톱 사용량까지 합산된 계정 단위 공식 데이터라 플랜 선택·캘리브레이션 없이 정확. 운용 규칙: 폴링 180초, 올바른 User-Agent 필수(없으면 429 지속), 토큰 만료 대응
공식 값이 없을 때	연동을 끄거나 조회에 실패하면 세션·주간 게이지를 --로 비우고 이유를 표시. 로컬 기록으로 %를 추정하지 않는다 (사례 4)
주의	2026-06-15부터 프로그래매틱 사용(Agent SDK, claude -p)은 별도 크레딧 풀 — v1은 entrypoint의 "sdk" 마커로 분리 표시

역할 분담(하이브리드): 세션/주간 게이지 % = 공식 엔드포인트(계정 단위, 웹 포함), 고양이 속도·오늘 토큰·스파크라인 = 로컬 JSONL(초 단위 실시간, Claude Code분). 공식 값이 없으면 게이지를 비우고 로컬 값으로 채우지 않는다.

M0 스파이크에서 발견한 것 (문서와 실물의 차이)

• 같은 응답이 스트리밍 청크 단위로 최대 6줄 중복 기록 → message.id + requestId 조합으로 중복 제거 필수 (미적용 시 2.9배 과대집계). 1,432건 → 고유 497건 실측.
• usage가 전부 0인 <synthetic> 모델 레코드 존재 → 명시적 스킵.
• 공식 세션 리셋 시각은 UTC 정시가 아님(실측 11:50Z) → 게이지 리셋은 공식 resets_at, 로컬 블록 계산은 속도·토큰량 전용으로 분리.
• 응답에 절대값(한도 달러/토큰) 없음 → 로컬 토큰으로 %를 환산할 수 없다 (트러블슈팅 사례 2, 4).

4. 핵심 기능

F1. 메뉴바 러너 (NSStatusItem)

• 러너 22종: 동물 15종(고양이·강아지·토끼·여우·펭귄·오리·공룡·고슴도치·병아리·개구리·판다·거북이·달팽이·문어·고래) 과 판타지 7종(유령·슬라임·로봇·UFO·닌자·유니콘·드래곤). 모두 직접 그린 벡터 캐릭터다.
• 도형(타원, 2관절 다리, 끝이 가늘어지는 꼬리)으로 그리고 발은 땅을 짚었다 들리는 궤적을 계산한다 (Characters/). 메뉴바는 단색 실루엣, 팝오버·설정은 외곽선과 명암을 넣은 컬러.
• 러너마다 선 자세의 키와 달리는 동안의 폭을 재서 36×22 설계 칸을 비슷하게 채우도록 자동으로 키운다. 병아리·펭귄처럼 작게 그린 러너도 메뉴바에서 잘 보인다.
• 메뉴바 크기: 상태 버튼(22pt)보다 높은 메뉴바 창(macOS 27에서 30pt)까지 러너 칸을 넓혀 그린다. (30pt 창이면 약 49×30pt.) 설정의 크기가 크게(기본)면 머리 위 효과 자리를 줄여 최대 1.1배로 키우고 (서 있는 몸과 테두리가 칸 높이에 들어가는 만큼까지) 칸을 그만큼 옆으로 넓힌다. 프레임은 레이어의 픽셀 크기 그대로 그려 늘려 붙이며 흐려지지 않게 한다.
• 잘림 방지: 공중제비·깡충·꾸벅처럼 칸 위아래를 벗어나는 장난은 바닥을 기준으로 줄여 칸 안에 넣는다 (뛰는 높이도 함께 줄어 제자리에 붙지 않는다. 팝오버 무대도 같다). 반복 동작은 한 주기 전체에 같은 맞춤을 걸어 프레임마다 크기가 출렁이지 않는다. 컬러 러너는 메뉴바와 반대 밝기의 1pt 테두리를 둘러 검은 머리·옷이 묻히지 않게 한다.
• 그림 러너는 투명한 여백을 뺀 실제 그림 영역으로 크기를 맞춘다.
• 동작 한 주기를 fps로 잘게 나눠 미리 그린다. 설정의 움직임: 절약 12 / 부드럽게 30 / 최고 60fps.
• 프레임은 Core Animation 키프레임으로 재생해 앱은 상태가 바뀔 때만 깨어난다 (사례 5).
• 색상 9종: 자동(메뉴바 글자색)·본래 색(캐릭터 고유색)·주황·하늘·분홍·초록·보라·노랑·무지개.
• 장난 22종: 깡충·공중제비·빙글·두리번·하트·노래·춤·기지개·깜빡·부르르·에취·반짝·꾸벅·어질어질·슝·실룩실룩 (25~70초마다 하나), 기상·하품·신남(상태가 바뀔 때), 뒤척·코풍선·꿈(잘 때). 설정에서 끌 수 있다.
• 내 러너: GIF나 PNG(여러 장이면 파일 이름 순서)를 불러와 러너로 쓴다. 테두리에 붙은 단색 배경은 지우고 이 Mac의 Application Support에만 저장한다. 사용량에 따라 빨라지고 장난도 똑같이 한다.
• Petdex: 설정 → 러너 → Petdex에서 찾기로 petdex.dev의 Codex 펫(약 4,900개)을 검색해 고른 펫만 내려받는다. 시트에서 서 있기·달리기·슬픔·기다리기 줄을 잘라 각각 선 자세·달리기·지침·잠에 쓰고, 손 흔들기 줄은 하트·노래·춤·반짝 장난에 쓴다. 손 흔들기를 쓰기 전에 받은 펫은 지우고 다시 받으면 생긴다. 펫은 사용자가 올린 팬아트라 앱에 싣지 않는다.
• 개인 팩: Sources/RunTime/LocalPack/(.gitignore)에 LocalRunnerPack을 따르는 러너를 두면 그 Mac에서 빌드한 앱에만 더해진다. 그림 러너의 프레임은 Sources/RunTime/Assets/LocalPack/(역시 .gitignore)에 두면 앱 번들에 함께 들어간다. 저작권이 있는 캐릭터를 공개 저장소에 싣지 않고 개인적으로 쓰는 경우를 위한 연결 고리다.
• 다크/라이트 메뉴바 대응: 동적 색상으로 그린 프레임을 상태 전환 시 1회 래스터라이즈(테마 변경 감지 시 재생성).
• 러너 옆 사용률 표시(옵션, 기본 끔): 세션·주간·높은 쪽 중 선택. 공식 값이 없으면 --%, 80%/95% 이상은 주황/빨강.

F2. 속도 매핑 (핵심 재미 요소)

• 신호: burn rate = 최근 60초 토큰 소모량(tokens/min), EMA(α=0.3) 스무딩.
• 5단계 상태 머신:

상태	조건 (tokens/min)	애니메이션	한 주기
쉬는 중	0 (5분 이상 무활동)	웅크려 잠, 숨쉬기 + Z	2.6초
걷는 중	1 ~ 2,000	걷기	1.25초
달리는 중	2,000 ~ 10,000	달리기 + 먼지	0.72초
질주 중	10,000 ~ 30,000	보폭 커짐 + 바람	0.54초
전력 질주	30,000+	달리기 + 무지개 꼬리 + 반짝이	0.44초

• 임계값은 Thresholds.swift 상수 + 설정에서 민감도(낮음/보통/높음) 3단 조절.
• 한도 임박 오버라이드: 사용률 80% 이상이면 상태와 무관하게 지쳐 앉은 러너 (헐떡임+땀방울), 95% 이상이면 빨간 러너와 깜빡이는 느낌표.

F3. 사용량 팝오버

러너 클릭 → NSPopover(다크, 폭 376pt).

┌───────────────────────────────────┐
│   러너가 달리는 무대 (시간대별 하늘)  [게임] │  ← 누르면 장난 + 말풍선, [게임]은 미니게임
└───────────────────────────────────┘
고양이 · 달리는 중 ⌄            8,420 토큰/분   ← 이름을 누르면 러너·색상·동작 메뉴
─────────────────────────────────────
세션 5시간               주간
42 %                     61 %
━━━━━━━━│──────          ━━━━━━━━━━━━│━
2시간 18분 뒤 초기화       목 16:44 초기화
약 1시간 12분 뒤 한도      Claude Code 92% · 채팅 8%
─────────────────────────────────────
최근 30분                       최고 62K/분
∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿∿
─────────────────────────────────────
오늘                   3.1M 토큰  약 $12.40
─────────────────────────────────────
● 공식 사용량 · 2분 전 갱신        ▥  ↻  ⚙  ⏻

• 게이지 %는 공식 값만 쓴다. 정수로 오는 값을 그대로 보여 주고 로컬 기록을 얹지 않는다 (사례 4). 공식 값을 못 받으면 --로 비우고, 비용은 "약 $" — 정직한 UI가 신뢰를 만든다.
• 색은 상태를 알릴 때만: 80% 전까지 무채색, 80% 주황, 95% 빨강. 이모지 없이 숫자와 짧은 문구만 둔다.
• 무대: 시간대별 하늘(아침·낮·노을·밤), 속도에 맞춰 산·구름·땅이 겹겹이 흐르고 전력 질주 때는 우주 배경. 러너를 누르면 장난을 치고 메뉴바 러너도 같은 장난을 한다. 화면 주사율대로 그리고 팝오버가 닫히면 멈춘다.
• 미니게임 "토큰 러너": 무대 오른쪽 위 게임 단추로 켠다. 고른 러너가 장애물(가시·버섯·선인장·나무·걸어오는 게와 드릴·박쥐)을 뛰어넘거나 숙여 피하고 코인을 모은다. 스페이스·↑·클릭으로 점프(길게 누르면 높이), ↓로 숙이기, esc로 나간다. 속도가 점점 빨라지고 100점마다 점수가 반짝이며, 최고 점수는 이 Mac에 저장한다.
  • 순위: 무대의 트로피 단추로 순위표(전체·이번 주)를 연다. 순위표 창에서 참여를 켜고 닉네임을 정하면, 이 Mac에서 최근 7일 동안 올린 점수보다 높을 때 점수를 올리고(이번 주 순위가 비지 않게) 게임 오버 화면에 "전체 N위"를 보여 준다. 참여는 기본으로 꺼져 있다.
  • 순위 소식: 팝오버가 열려 있으면 30초마다, 참여 중이면 닫혀 있어도 10분마다 요약(/v1/summary)을 받아 지난번과 견준다. 새 1위, 1위의 기록 경신, 내가 1위가 됨, 이번 주 1위 교체, 누가 나를 추월함을 러너가 말풍선으로 알려 주고, 자리를 비운 사이 생긴 소식은 다음에 팝오버를 열 때 차례로 들려준다. 게임 중에는 판이 끝난 뒤에 말한다. 참여하지 않으면 설치 ID 없이 공개 정보(1위와 상위 점수)만 받는다.
  • 라이벌: 게임 중 내 위의 사람들이 차례로 목표가 된다. 위쪽에 "다음 목표 이름 점수 (-남은 점수)"가 뜨고, 그 점수에 닿는 지점에 깃발이 다가오며, 넘으면 "이름 추월!" 배너가 뜬다. 순위표 창은 열려 있는 동안 30초마다 새로 받는다.
  • 순위 서버는 server/leaderboard/(Cloudflare Workers + D1). 앱이 오픈소스라 조작을 완전히 막을 수는 없어서, 플레이 시간 안에 규칙상 낼 수 없는 점수(최고 속도·점수율·코인 상한으로 계산), 같은 사람이 3초 안에 다시 올리는 요청, 같은 IP에서 1분에 6번 넘게 올리는 요청을 거른다. IP는 날마다 바뀌는 값과 함께 해시해 횟수만 세고 1시간 뒤 지운다. 규칙 숫자는 앱(RunnerGame.rulesVersion)과 서버(rules.js)에 같이 두고 양쪽 테스트가 같은 값을 확인한다.
  • 규칙은 GameCore 라이브러리에 화면과 떼어 두었다. 1/120초 고정 간격 물리, 착지 직전·이륙 직후 입력 보정, 최소 점프 높이, 너그러운 판정 상자. 판정 상자는 캐릭터와 상관없이 같아 어떤 러너로 해도 조건이 같다.
  • 장애물 간격은 Chromium T-Rex Runner(BSD 3-Clause) 공식을 따르고, 점프 시간으로 잰 하한을 더했다. 무작위 씨앗 40개로 모든 장애물을 넘거나 지나갈 수 있는지 테스트한다.
  • 그림과 효과음은 Kenney의 CC0 에셋(Pixel Platformer, Digital Audio). 출처는 Assets/Game/CREDITS.txt.
• 게이지 눈금은 창(5시간/주간)의 경과 시간 — 막대가 눈금보다 앞서면 시간보다 빨리 쓰는 중.
• "약 N분 뒤 한도"는 최근 30분 공식 세션 %의 오름세로 계산하고, 초기화가 먼저 오면 "초기화 전까지 여유".
• 주간 아래는 사용처가 둘 이상이면 공식 사용처 비중(Claude Code·채팅…), 아니면 이 기기의 모델 비중.
• 스파크라인에 마우스를 올리면 그 분의 tokens/min, 일별 상세는 모델 계열(Opus·Sonnet·Haiku·Fable)별 막대.

갱신 전략

• 공식 % 폴링 180초(429 방지 안전 간격) + 팝오버 여는 순간 즉시 1회 재조회 (직전 30초 이내면 생략).
• 조회 뒤 공식 창의 리셋 시각이 지나면 이전 %를 보여 주지 않고 0%로 두고, 새 값을 받을 때까지 30초 간격으로 다시 조회한다.

F4. 알림

• 세션/주간 80%·95% 도달 시 각 1회 macOS 알림. 예: "세션 사용량 80%" / "현재 속도로 약 1시간 12분 뒤 한도에 닿습니다." 창 리셋 시 발송 기록 초기화, 70→96% 건너뛰면 95만 발송(스팸 방지) — 정책을 순수 로직으로 분리해 단위 테스트.
• 5시간 블록 리셋 시 "세션 초기화" 알림 (옵션, 기본 off).
• 알림과 지친 고양이는 공식 값으로만 판단한다. 공식 값이 없으면(시작 직후·실패) 평가하지 않는다.

F5. 설정 (UserDefaults)

• 공식 연동 on/off (끄거나 조회에 실패하면 세션·주간 게이지를 비운다)
• 민감도 3단 / 러너(22종 + Petdex 펫 + 내 러너, 움직이는 미리보기 타일, 이름 검색)·메뉴바 크기 2단·색상 9종 / 움직임(12·30·60fps) / 가끔 장난치기 / 메뉴바 사용률 / 한도·새 세션 알림 / 로그인 시 자동 시작(SMAppService) / 폴링 주기(기본 3초)
• 정보: 버전과 빌드 커밋(설치된 앱이 어느 커밋인지 확인용), 데이터 폴더 열기

5. 기술 아키텍처

스택: Swift 5.9+ · SwiftUI(팝오버/설정) + AppKit(NSStatusItem) · macOS 13+ · SPM. 테스트 가능한 코어(UsageCore 라이브러리)와 앱 계층 분리.

RunTime/
├── Sources/GameCore/           # 미니게임 규칙 (물리·장애물·점수) — 게임 테스트 32개의 대상
├── server/leaderboard/         # 미니게임 순위 서버 (Cloudflare Worker + D1, 규칙·통합 테스트)
├── Sources/UsageCore/          # 순수 로직 — 단위 테스트 70개의 대상
│   ├── JSONLWatcher.swift      #   ~/.claude/projects 재귀 감시, 파일별 오프셋 증분 파싱
│   ├── JSONLParser.swift       #   스키마-관용 파싱, <synthetic> 스킵
│   ├── UsageStore.swift        #   중복제거(message.id+requestId) + 집계(오늘/주간/모델/스파크라인)
│   ├── BlockCalculator.swift   #   5시간 블록(UTC floor)
│   ├── BurnRateMeter.swift     #   60초 창 tokens/min + EMA
│   ├── OAuthUsageProvider.swift#   공식 % 폴링: 토큰 캐시 + security 서브프로세스 + 파일 폴백
│   ├── GaugeMath.swift         #   공식 값 게이지·창 초기화 처리, 공식 오름세로 한도 도달 시간
│   ├── UsageEvaluator.swift    #   틱 판단: 공식 값 유효성(유예 15분)·게이지·한도 단계
│   ├── WeeklyWindow.swift      #   롤링 7일 / 공식 리셋 시각을 7일 단위로 굴리기
│   └── UsageAlerts.swift       #   80/95% 알림 정책 (창별 1회)
├── Sources/RunTime/
│   ├── App/                    #   AppDelegate(NSStatusItem), UsageEngine, AppSettings
│   ├── Characters/             #   러너 22종 벡터 골격(Quadruped·Bird·Reptile…), 장난 22종, 효과, 내 러너·Petdex·개인 팩
│   ├── SpriteEngine/           #   SpriteAnimator(Core Animation 재생), MenuBarCanvas(칸 크기), 프레임 생성, 래스터라이저, 점검 시트·메뉴바 점검
│   ├── UI/                     #   PopoverView, RunnerStage(무대), Theme, GaugeBar, Sparkline, SettingsView, RunnerPicker, PetdexBrowser
│   ├── Game/                   #   GameSession(무대 위 한 판: 입력·효과·점수판), GameAssets, GameSound, GameShots(점검)
│   ├── Services/               #   Notifier(UserNotifications), LaunchAtLogin(SMAppService)
│   └── Assets/                 #   PNG 넣으면 자동 교체되는 스프라이트 폴더
├── docs/                       #   개발 기록 (이 문서)
└── scripts/                    #   build-app.sh, setup-signing.sh, install.sh, make-icon.sh, test.sh

성능 예산 vs 실측: 유휴 CPU < 0.5% → 0.05%(잠자는 러너, 기본 30fps 설정), 전력 질주 30fps 0.5%, 메모리(phys_footprint) < 50MB → 17MB(빈 데이터) / 21MB(하루 5천만 토큰 실사용). 파싱은 백그라운드 큐, 풀스캔은 시작 시 1회, 이후 파일 오프셋 기억 증분. 유휴 측정은 CLAUDE_CONFIG_DIR로 빈 데이터 디렉토리를 지정한 격리 인스턴스로, CPU는 30초 누적 CPU 시간으로 잰다.

대안 스택 검토: Python + rumps로 반나절 MVP 가능하나 애니메이션 fps·배포에 한계 → Swift 채택. Electron은 러너 앱 용도로 리소스 과다라 배제.

6. 보안 설계 — macOS 키체인 접근 (필수 준수 규칙)

Claude Code는 macOS에서 OAuth 토큰을 키체인 항목 Claude Code-credentials(로그인 키체인)에 저장한다. 이 항목은 ACL로 보호되어 다른 앱이 읽으면 macOS가 암호 프롬프트를 띄우는 것이 정상 동작이다. 반복 원인과 대응:

원인	대응 규칙
매 폴링(3분)마다 키체인 읽기	금지. 토큰을 메모리 캐시, 만료(~60분) 시에만 재읽기 → 빈도 1/20
"허용"만 클릭(1회성)	첫 실행 안내에서 "항상 허용(Always Allow)" 누르도록 안내
빌드마다 코드서명 변경(ad-hoc) → "항상 허용" 무효화	개발 중에도 고정 서명 identity 사용 (self-signed 인증서 생성·고정 스크립트 제공)
앱이 Security.framework 직접 호출	/usr/bin/security find-generic-password ... 서브프로세스 — ACL 대상이 Apple 서명 불변 바이너리가 되어 리빌드해도 프롬프트 재발 없음 (트레이드오프는 README 한계에 적음)
그래도 프롬프트가 싫은 경우	폴백 순서: ⑴ ~/.claude/.credentials.json 파일 우선(프롬프트 없음) ⑵ 키체인 ⑶ 실패 시 게이지를 비우고 이유 표시

절대 금지: security unlock-keychain 자동화, 키체인 암호 저장·자동입력 — 편하자고 보안을 무너뜨리는 안티패턴. OAuth 토큰은 읽기 전용, Anthropic 외 어디에도 전송·저장·로깅하지 않는다. (Petdex 목록과 펫 그림은 Petdex에서 찾기를 열 때만 petdex.dev에서 받고, 이때 토큰이나 사용량은 보내지 않는다. 미니게임 순위는 참여를 켠 경우에만 무작위 설치 ID·닉네임·점수·코인 수·플레이 시간·앱 버전을 순위 서버로 보내고, 순위 소식을 받으려고 10분마다 ID와 함께 순위 요약을 받는다. 참여하지 않아도 팝오버를 열면 30초마다 ID 없이 공개 순위 요약을 받는다. 순위표 창의 "내 기록 지우기"로 서버에서 지울 수 있다. 업데이트 확인은 30분마다 GitHub API에 공개 저장소의 커밋 비교만 묻고, 사용자 정보는 보내지 않는다.)

7. 트러블슈팅 기록 (5건)

사례 1. macOS 키체인 암호 프롬프트 반복

TL;DR — 토큰을 읽을 때마다 키체인 암호 프롬프트가 반복됐다. 원인을 "버그"가 아닌 키체인 ACL의 정상 보안 동작으로 규정하고, 접근 빈도(메모리 캐시)·승인 방식(항상 허용 안내)·코드서명(고정 identity + security 서브프로세스) 3개 축으로 분해해 프롬프트를 최초 1회로 줄였다. 핵심 발견: ACL은 코드서명 단위로 신뢰를 기억하므로 ad-hoc 서명은 빌드마다 승인이 무효화된다 — 서명 전략은 배포뿐 아니라 런타임 UX 문제다. unlock-keychain 자동화류는 의도적으로 배제. (원인·대응 상세 표는 §6 참조)

사례 2. 실시간 보간 게이지 폭주 — 오탐 "100% 경고"

TL;DR — 공식 % 위에 로컬 소모분을 얹는 보간 게이지가 몇 분 만에 100%로 폭주하며 빨간 고양이·95% 오탐 알림을 냈고, 팝오버를 열면(재조회) 잠깐 정상으로 돌아와 "클릭해야 갱신되는 버그"처럼 보였다.

	코드의 가정	실측
공식 1%에 해당하는 로컬 토큰	5,000 (플랜 한도 500K÷100)	약 60,000 (블록 4M ÷ 공식 63%)
5분간 30만 토큰 소모 시 보간	+60%p (폭주)	+5.1%p

원인은 단위가 다른 두 데이터를 고정 상수로 환산한 것 — 로컬 로그 토큰은 캐시 읽기가 지배해 실제 한도 소진의 수십 배 스케일이었다. 환산 비율을 실측 역산(조회 시점 창 토큰 ÷ 공식 %)으로 바꾸고, 역산이 불안정한 구간(공식 5% 미만)은 보간을 생략하며, 알림의 잔여 시간 추정도 같은 스케일로 일원화(GaugeMath 모듈 + 테스트 6개). 같은 시나리오에서 123%→100% 폭주가 **68.1%**로 정확해졌다. 배운 점: 이종 소스를 섞을 때는 단위부터 검증하고, 모르는 환산 비율은 상수로 가정하지 말고 시스템이 주는 실측으로 캘리브레이션하라. (이후 사례 4에서 보간과 추정 모드를 빼고 게이지는 공식 값만 쓰게 했다.)

사례 3. "새로고침이 안 돼요" — 스로틀과 App Nap

TL;DR — 두 갈래 증상. ① 새로고침 버튼이 동작하지 않음: 팝오버를 여는 순간 공식 %를 이미 조회하고 30초 스로틀(429 방지)이 걸리므로, 직후 버튼을 눌러도 항상 생략됐다 → 사용자 명시 동작은 스로틀을 우회(연타 방지 5초만 유지)하도록 경로를 분리. ② 장시간 실행 중 데이터 갱신 정지 의심: 메뉴바 전용 앱은 App Nap 대상이라 백그라운드 타이머가 지연될 수 있는데, 애니메이션 타이머(메인 스레드)는 계속 돌아 "살아있는데 데이터만 멈춘" 것처럼 보인다 → ProcessInfo.beginActivity로 냅 방지 + os.log 기반 진단(3초 틱 요약, 공식 조회 결과, 틱 지연 경고)을 내장해 재발 시 log stream 한 줄로 확인 가능하게 했다. 배운 점: 자동 폴링의 보호 장치(스로틀)가 사용자 명시 동작까지 삼키면 "고장"으로 인식된다 — 경로를 분리하고, 관측 가능성(logging)을 제품에 내장하라.

사례 4. 세션·주간 %가 /usage와 가끔 다르게 보임

TL;DR — 게이지는 공식 % 위에 이 기기의 로컬 사용분을 얹어 보간했다. 원인을 다섯 가지로 나눠 고쳐 보다가, 보간 자체를 빼고 공식 값만 쓰는 쪽으로 정리했다.

원인	증상	대응
보간 비율을 로컬 5시간 블록(UTC 정시 내림)으로 계산	공식 창(예: 12:10~17:10)과 어긋나 보간이 커지거나 작아짐	보간 제거
조회 뒤 창이 초기화돼도 다음 조회까지 이전 %를 유지	초기화 직후 최대 3분(실패 시 15분) 97% 같은 옛 값과 빨간 경고	리셋 시각이 지나면 0%, 30초 간격 재조회
토큰 수로 환산 (대부분 단가가 낮은 캐시 읽기)	작업 종류에 따라 보간이 흔들림	보간 제거
이 기기 기록에 없는 사용분 (다른 기기·웹)	실측 17분 동안 실제 1%p당 비용이 창 평균의 세션 1.3배, 주간 4.4배	보간 제거
resets_at이 조회마다 1초 안쪽으로 흔들림 (17:09:59.75 → 17:10:00.47)	알림 추적기가 매 조회를 새 창으로 봐 80%/95% 알림이 반복될 수 있음	창 식별자를 분 단위로 반올림

비용 환산과 공식 창 정렬로 보간 오차를 세션 4%p → 1%p 수준까지 줄였지만, 공식 값은 조회 시점에 늘 정확하고 조회 사이 지연은 최대 3분이다. 그래서 게이지는 공식 값만 쓰고, "약 N분 뒤 한도"도 최근 공식 값의 오름세로 계산한다. 같은 이유로 공식 값이 없을 때 플랜 한도로 계산하던 추정 모드도 지웠다. 값이 없으면 --로 비운다. 배운 점: 정확한 원천이 있으면, 그 사이를 메우는 추정은 원천과 범위·단위가 같다고 보장할 수 있을 때만 쓴다.

사례 5. 메뉴바 애니메이션이 CPU 18%를 씀

TL;DR — 프레임을 잘게 나누자 30fps에서 CPU 18%(60fps 26%)가 나왔다. 설치돼 있던 이전 빌드도 42%였다. 프레임마다 NSStatusBarButton.image를 바꾸면 버튼 셀 전체를 다시 그린다. 프레임을 미리 래스터라이즈해 CAKeyframeAnimation(keyPath: "contents")로 넘기자 재생을 시스템 렌더 서버가 맡아 0.5%(잠잘 때 0.05%)로 내려갔다. 버튼 크기와 사용률 글자 배치는 투명한 자리 표시 이미지로 잡고 러너는 그 위 레이어에서 돈다. 배운 점: 반복 애니메이션은 앱이 매 프레임 그리지 말고 렌더 서버에 맡긴다.

8. 마일스톤 & 결과

단계	계획	완료 기준	결과
M0 (0.5일)	JSONL 스키마 실물 검증, ccusage 블록 로직 대조, OAuth 엔드포인트 실측	JSONL 스키마 정리 + 파서 단위테스트	✅ 중복 6줄·synthetic 발견, 엔드포인트 HTTP 200 실측
M1 MVP (2일)	메뉴바 러너 + burn rate 연동 + 최소 팝오버	실사용 중 고양이 속도 체감 일치	✅
M2 (2일)	공식/주간 게이지, 플랜 설정·캘리브레이션, 스파크라인	ccusage 오차 < 2%	✅ 오차 0.00%
M3 (1~2일)	알림, 지친 고양이, 자동 시작, 서명, README	dmg 배포 가능	✅ + 소스 배포(install.sh) 채택
v1.1	러너 테마 3종, 일별 상세, 무지개 전용 에셋 경로, 프로그래매틱 분리 표시	—	✅
v1.2	벡터 러너 22종·장난 22종·팝오버 무대·내 러너, 게이지 공식 값 전용	/usage 일치, 질주 CPU < 0.5%	✅ CPU 0.5%, 테스트 70개

9. 수용 기준 (Acceptance Criteria) — 최종 체크

• Claude Code에서 대화 시 3초 이내에 고양이 속도가 반응한다 (3초 증분 폴링)
• 5분 무활동 시 고양이가 잠든다 (상태머신 테스트 + 실측)
• 공식 연동 상태에서 세션/주간 %가 /usage 표시값과 일치 (동일 엔드포인트, 보간 없음)
• 공식 연동 off·실패 시 게이지를 --로 비우고 이유 표시 (로컬 추정 없음)
• 세션 토큰 합계가 ccusage blocks 현재 블록과 오차 2% 이내 → 0.00%
• 80%/95% 알림이 각 1회만 발송 (정책 단위테스트 7개)
• 유휴 CPU < 0.5% → 0.05% 실측 (30fps 질주 0.5%)

10. 리스크 & 대응

리스크	대응
비문서화 usage 엔드포인트 변경·차단	게이지를 비우고 이유 표시(앱이 죽지 않음), 폴링 180초·User-Agent 준수, 응답 스키마 관용 파싱(limits[] 배열 폴백 포함). 토큰은 로컬 읽기 전용
Claude Code의 JSONL 포맷 변경	파서 스키마-관용(필드 누락 시 skip), 버전 감지
공식 값이 없을 때 사용률을 모름	게이지를 --로 비우고 상태 줄에 이유 표시. 속도·오늘 사용량은 로컬 기록으로 계속 표시
캐릭터 저작권	러너는 전부 직접 그린 벡터(장르 전형만 참고), 냥캣·유명 캐릭터 미사용. 내 러너 그림은 앱에 싣지 않고 사용자 Mac에만 저장
프로그래매틱 사용(별도 크레딧 풀) 혼입	entrypoint "sdk" 마커로 분리 표시 + 관용 판별임을 문서 명시
다수 프로젝트 폴더로 시작 풀스캔 지연	파일 mtime 필터(최근 8일) + 오프셋 증분 파싱

11. 배운 점 종합

1. 실물 우선: 문서·통념 대신 실제 JSONL 1,432건을 먼저 분석해 중복 기록이라는 결정적 함정을 첫날 발견했다. 스파이크 비용 반나절이 이후 모든 집계의 신뢰를 만들었다.
2. 보안 동작과 버그의 구분: 키체인 프롬프트를 우회하지 않고 OS 규칙 안에서 접근 빈도·신뢰 단위를 재설계했다. 트레이드오프는 문서화로 사용자에게 선택권을 줬다.
3. 이종 데이터 결합은 단위 검증부터: 같은 "토큰"이라도 계정 한도와 로그의 토큰은 다른 물리량 — 고정 상수로 환산하지 않고, 정확한 원천이 있으면 그것만 쓴다.
4. 관측 가능성은 제품 기능: "갱신이 안 된다"는 모호한 제보를 위해 진단 로깅을 내장했다 — 다음 제보는 log stream 한 줄로 원인이 좁혀진다.
5. 정직한 UI: 공식 값이 없으면 숫자를 지어내지 않고 --로 비운다. 정확도의 한계를 숨기지 않는 것이 신뢰를 만든다.

12. 참고 자료

• OAuth usage 엔드포인트 논의(Claude-Code-Usage-Monitor #202): Maciek-roboblog/Claude-Code-Usage-Monitor#202
• 공식 % 트레이 앱 선례(usage-monitor-for-claude): https://github.com/jens-duttke/usage-monitor-for-claude
• ccusage 5시간 블록 리포트: https://ccusage.com/guide/blocks-reports
• 실시간 모니터 선례(Claude-Code-Usage-Monitor): https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor
• Claude Code 한도 해설(2026): https://www.morphllm.com/claude-code-usage-limits
• 사용량 확인 가이드(/usage): https://sessionwatcher.com/guides/how-to-check-claude-code-usage
• RunCat (UX 레퍼런스): https://kyome.io/runcat/
• Chromium T-Rex Runner (미니게임 장애물 간격·속도 규칙, BSD 3-Clause): https://chromium.googlesource.com/chromium/src/+/main/components/neterror/resources/
• Kenney 에셋 (미니게임 그림·효과음, CC0): https://kenney.nl/assets/pixel-platformer · https://kenney.nl/assets/digital-audio