Claude Code 사용량을 안드로이드 위젯으로 보는 가장 현실적인 방법

Claude Code와 Codex를 번갈아 쓰다 보면 작업보다 잔여 사용량을 먼저 계산하게 된다. 터미널을 열지 않고 안드로이드 홈 화면에서 한도를 확인할 수 있을까. 답은 ‘가능하지만 PWA만으로는 부족하다’이다. 위젯 디자인에 앞서 어떤 수치를 어디서 가져올지 정해야 한다.

PWA 바로가기와 안드로이드 위젯은 다른 기능이다

PWA를 설치하면 홈 화면에 아이콘을 둘 수 있다. 아이콘을 누르면 웹 대시보드가 앱처럼 열린다. 하지만 날씨나 배터리 카드처럼 홈 화면에서 값이 계속 바뀌는 Android App Widget은 아니다.

Google 문서가 안내하는 정식 위젯은 AppWidgetProvider를 앱 매니페스트에 등록하고 별도 메타데이터와 화면 구성을 포함한다. Jetpack Glance를 쓰면 Kotlin과 Compose에 가까운 문법으로 만들 수 있지만 결과물은 여전히 설치 가능한 APK 안에 들어간다. ‘위젯만 따로 설치’하는 것보다 작은 안드로이드 앱에 위젯 하나를 넣는 구조가 정확하다.

PWA가 쓸모없는 것은 아니다. 상세 기록과 설정 화면은 웹으로 만들고 네이티브 위젯에는 사용률과 초기화 시각만 표시하면 된다. 앱을 누르면 PWA가 열리도록 역할을 나누면 안드로이드 코드를 작게 유지할 수 있다.

Claude Code는 상태 표시줄 JSON에서 한도 값을 얻을 수 있다

Anthropic의 최신 Claude Code 문서는 커스텀 상태 표시줄에 구조화된 세션 JSON을 전달한다고 설명한다. Claude Code v2.1.251 이상에서는 Pro·Max 구독자의 rate_limits 객체에 5시간과 7일 구간의 사용률과 초기화 시각이 포함된다. 첫 API 응답 전에는 값이 없을 수 있으므로 빈 상태도 처리해야 한다.

가장 단순한 수집기는 ~/.claude/statusline.sh다. ~/.claude/settings.json의 statusLine.command가 이 스크립트를 가리키게 한 뒤 표준 입력에서 rate_limits.five_hour.used_percentage, rate_limits.seven_day.used_percentage, 각 resets_at만 뽑는다. 출력은 기존 터미널 상태 표시줄에 쓰고 축약한 JSON은 로컬 파일에도 저장한다.

상태 표시줄은 작업 중 자주 실행된다. 호출할 때마다 원격 서버에 POST하면 지연이 발생하고 불필요한 요청이 쌓인다. 마지막 전송 시각을 파일에 기록해 두고 일정 시간이 지났을 때만 업로드하는 편이 낫다. Anthropic도 상태 표시줄의 비싼 작업에는 캐시를 두라고 안내한다.

전송할 데이터는 제품명, 두 사용률, 초기화 시각, 갱신 시각이면 충분하다. 원본 입력에 들어 있는 작업 경로, 세션 ID, 저장소 정보, transcript 경로는 제거해야 한다. 사용량 위젯을 만들면서 개발 환경의 위치와 세션 흔적까지 외부로 보낼 이유는 없다.

Cloudflare 방식은 저장소와 읽기 API를 함께 만든다

구성 순서는 명확하다. 수집 스크립트가 축약 JSON을 Worker의 쓰기 API로 보내면 Worker가 최신 값 하나를 KV에 저장한다. 안드로이드 앱과 PWA는 읽기 API에서 같은 값을 가져온다. 정적 HTML·CSS·JavaScript도 Workers Static Assets로 함께 배포할 수 있다.

Cloudflare 공식 문서에 따르면 Workers 무료 플랜에는 제한된 Worker와 KV 사용량이 포함된다. 개인 위젯처럼 몇 분 간격으로 값 하나를 쓰고 읽는 용도라면 구조가 단순하다. 다만 ‘무료 서빙’과 ‘안전한 공개’는 같은 말이 아니다.

쓰기 API에는 충분히 긴 토큰이나 서명 검증을 붙여야 한다. 토큰은 Worker secret과 로컬 비밀 저장소에 둔다. 읽기 API도 인증 없이 열어 두면 생활 패턴과 작업 시간을 유추할 수 있다. Cloudflare Access를 적용하면 로그인 정책 뒤에 둘 수 있다. Tunnel로 사내·가정 내부 서비스와 연결할 때는 Access 정책을 먼저 만들어야 한다. Cloudflare도 정책 없는 공개 Tunnel은 인터넷 전체에 노출된다고 경고한다.

써본 사람들 사이에서는 한눈에 한도를 보는 만족감보다 인증 만료와 갱신 실패를 손보는 일이 더 커졌다는 반응도 있다. 화면에는 마지막 갱신 시각과 오류 상태를 반드시 표시해야 한다. 오래된 수치를 현재 값처럼 보여주는 위젯은 없는 것보다 위험하다.

Tailscale은 서버를 공개하지 않지만 휴대전화도 참여해야 한다

공개 API를 만들기 싫다면 로컬 웹 서버와 Tailscale Serve를 조합할 수 있다. Tailscale 문서에 따르면 tailscale serve는 로컬 서비스를 같은 tailnet 안에서만 공유한다. 수집기는 로컬 JSON만 갱신하고 휴대전화 위젯은 Tailscale 주소로 접속한다.

공인 포트와 공개 도메인이 필요 없어 개인용으로 이해하기 쉬운 방식이다. 반면 휴대전화에 Tailscale이 연결돼 있어야 하고 회사 단말의 VPN·MDM 정책과 충돌할 수 있다. 회사 네트워크가 개인 터널이나 신규 기기 등록을 막는다면 기술적으로 안전하더라도 사용할 수 없다.

업무 장비가 섞인 환경에서는 회사 정책이 아키텍처의 최상위 조건이다. 허가받지 않은 터널로 우회하지 말고 개인 장비에서만 수집하거나 조직이 제공하는 사용량 대시보드를 쓰는 편이 맞다.

위젯은 15분 단위 표시판으로 설계해야 한다

안드로이드 앱에는 GlanceAppWidget, GlanceAppWidgetReceiver, res/xml의 provider 정보를 넣는다. WorkManager가 읽기 API를 주기적으로 호출해 결과를 로컬 저장소에 기록한 뒤 updateAll()로 위젯을 다시 그린다. 위젯에는 Claude 5시간 사용률, 주간 사용률, 다음 초기화 시각, 마지막 동기화 시각 정도만 두면 된다.

Google은 백그라운드 위젯 갱신에 제약을 둔다. updatePeriodMillis는 최대 30분 간격이고 WorkManager를 이용한 주기 작업도 일반적으로 15분보다 촘촘하게 예약할 수 없다. 초 단위 실시간 계기판이 아니라 작업 전 상태를 살피는 표시판으로 설계해야 한다. 필요하면 새로고침 버튼으로 앱을 깨워 즉시 동기화를 요청한다.

Codex도 최신 문서에서 SessionStart, SessionEnd 같은 훅을 제공한다. 그러나 Claude Code의 rate_limits와 동일한 구독 한도 필드가 공식 훅 입력에 보장된다고 확인되지는 않는다. 불안정한 터미널 문자열이나 transcript를 파싱해 두 제품을 억지로 합치면 업데이트 때 깨질 가능성이 크다.

첫 버전은 Claude Code의 공식 상태 표시줄 필드만 표시하는 편이 낫다. Codex는 공식적으로 안정된 사용량 인터페이스를 확인한 뒤 같은 JSON 스키마에 추가할 수 있다. 하루에 한두 번 궁금한 정도라면 /usage와 상태 표시줄이면 충분하다. 작업 순서를 한도 초기화에 맞춰 자주 바꾸는 사람에게만 이 작은 APK와 동기화 서버를 유지할 가치가 있다.