# AI Limits Desk — Windows 미리보기 0.1.1

Codex와 Claude Code의 구독 한도, 초기화 예정 시각, 알림을 모아 보는 한국어 윈도우 트레이 앱입니다.

## 실행

1. `AI-Limits-Desk-Windows-x64.zip`을 원하는 폴더에 **모두 압축 해제**합니다.
2. `AI Limits Desk.exe`를 실행합니다. 실행 파일만 다른 폴더로 옮기지 마세요.
3. `연결 및 설정`에서 서비스를 연결합니다.

Windows 10/11 x64용 패키지입니다. 앱 자체는 별도 Node.js 설치 없이 실행됩니다. 코드 서명되지 않은 개인용 미리보기 빌드입니다. 이 버전은 Linux에서 실제 앱 실행·Codex 조회를 검증했습니다. Windows의 트레이·알림·자동 실행은 직접 확인하지 못했습니다.

## Codex 연결

이 PC에 설치된 Codex CLI의 로그인 상태를 사용합니다. API 키를 앱에 붙여 넣을 필요는 없습니다.

- CLI가 없다면 [공식 설치 안내](https://developers.openai.com/codex/cli/)를 따라 설치합니다.
- 터미널에서 `codex login`을 실행하고 ChatGPT 계정으로 로그인합니다.
- 앱에서 `새로고침`을 누릅니다. 자동 탐색이 안 되면 `연결 및 설정 → 실행 파일 선택`으로 `codex.exe` 또는 npm 설치 폴더의 `@openai/codex/bin/codex.js`를 지정합니다.

앱은 Codex의 [공식 App Server](https://learn.chatgpt.com/docs/app-server)에서 `account/rateLimits/read`만 조회합니다. 대화를 생성하거나 초기화 크레딧을 소비하지 않습니다. 반환된 구간과 모델별 한도를 표시하며, 특정 계정에 5시간 구간이 없으면 만들지 않습니다. 일반 ChatGPT 채팅의 모든 모델 한도를 의미하지는 않습니다. API 키 기반 계정에서는 구독 한도가 나오지 않을 수 있습니다.

## Claude 연결

이 버전은 **Windows에서 실행하는 Claude Code**와 연결됩니다. Claude.ai 웹이나 데스크톱 앱의 수치를 직접 폴링하지 않습니다.

1. Claude Code에 구독 계정으로 로그인합니다.
2. `연결 및 설정 → Claude 연결`을 누릅니다.
3. Claude Code를 다시 시작하고 한 번 대화합니다.
4. 공식 statusLine 응답에 한도가 포함되면 앱에 나타납니다.

[Claude 공식 statusLine 문서](https://code.claude.com/docs/en/statusline)에 명시된 `rate_limits.five_hour`와 `rate_limits.seven_day`를 수집합니다. 문서상 Pro/Max 구독의 첫 응답 이후 제공되며, 각각의 구간은 생략될 수 있습니다. 모델별 별도 한도·추가 결제 잔액은 이 버전에 포함하지 않습니다.

`%USERPROFILE%\.claude\settings.json`의 `statusLine`만 연결용 명령으로 설정합니다. `CLAUDE_CONFIG_DIR` 환경 변수가 있으면 해당 폴더를 사용합니다. 이전 statusLine 설정은 앱 데이터 폴더의 `claude-installation.json`에 보관하며, **연결 해제 시 복원**합니다. 그 뒤 직접 바꾼 설정은 자동으로 덮어쓰지 않습니다. 연결용 PowerShell 실행 범위에서만 ExecutionPolicy Bypass를 사용하며 시스템 실행 정책은 변경하지 않습니다.

Claude Code가 응답하지 않거나 다른 기기·웹에서만 사용하면 최신 수치가 들어오지 않습니다. 앱의 새로고침 버튼이 Claude 서버를 직접 조회하는 것은 아닙니다. Windows 앱과 CLI가 서로 다른 계정으로 로그인돼 있다면 CLI 계정의 한도가 표시됩니다. WSL 내부 CLI는 현재 자동 탐색·연결 대상이 아닙니다.

## 표시와 알림

- **트레이 숫자는 주간 사용률(%)**입니다. `CX`는 Codex, `CL`은 Claude입니다. `CX 19`는 Codex 주간 한도의 19%를 사용했다는 뜻입니다.
- 두 서비스를 각각의 트레이 아이콘으로 표시합니다. 마우스를 올리거나 우클릭하면 주간 남은 비율과 초기화 예정 시각을 볼 수 있습니다.
- 주간 한도가 없거나 초기화 확인을 기다리면 `--`로 표시합니다. 오래된 수치는 회색 배경·노란 밑줄로 표시합니다.
- 대표 Codex 주간 한도가 없을 때 다른 모델의 주간 한도를 대신 표시하지 않습니다.
- Windows가 새 아이콘을 숨기면 작업 표시줄의 `^` 안에서 `CX`와 `CL`을 꺼내 보이게 할 수 있습니다.

- Codex 새로고침: 1/2/5분 중 선택, 기본 2분.
- Claude 스냅샷 확인: 5초 간격. 10분이 지난 수치는 이전 기록으로 표시.
- 초기화 예정 시각이 지나도 임의로 0% 사용 처리하지 않음. 새 구간이 확인될 때 갱신.
- 한도 알림: 기본 85% 사용, 같은 구간의 같은 기준은 한 번만 알림.
- 초기화 알림: 새 구간에서 사용률이 내려간 실제 수치를 받았을 때 알림.
- Windows 알림은 트레이 알림으로 표시하며 집중 지원/방해 금지 설정의 영향을 받음.
- 창을 닫으면 트레이에 유지. 완전히 끝내려면 트레이 메뉴에서 `종료`.
- 윈도우 로그인 시 자동 실행은 설정에서 선택, 기본 꺼짐.
- 기록은 최근 7일의 **관측한 한도 사용률**. 토큰 합계나 일일 사용량 추정치가 아님. CSV 내보내기 지원.

## 데이터와 삭제

`연결 및 설정 → 데이터 폴더 열기`에서 확인할 수 있습니다. 기본 경로는 `%APPDATA%\AI Limits Desk\data`입니다.

- 구독 한도 스냅샷, 갱신 시각, 설정, 알림 중복 방지 상태를 로컬 저장.
- 비밀번호·OAuth 토큰·대화 본문·이메일은 저장하지 않음.
- Claude 원본 statusLine JSON 전체를 저장하지 않고 사용량 필드만 선택.
- 외부 분석 서버나 별도 회원가입 없음. Codex CLI가 사용량 조회를 위해 OpenAI에 연결함.
- 배포 ZIP에는 개발 환경의 실제 계정 스냅샷이 포함되지 않음.

앱을 삭제하거나 폴더를 옮기기 전에 Claude 연결 해제 및 자동 실행 해제를 권장합니다. 앱 폴더를 옮겼다면 Claude 연결도 새 위치에서 다시 설정하세요. 필요하면 앱 데이터 폴더까지 지워 기록을 제거할 수 있습니다.

## 개발 및 검증

- `npm ci` 후 `npm test`: 한도, 만료, 알림, 스냅샷 정제, 설정 복원, RPC 오류/타임아웃 검사.
- `node scripts/ui_smoke.cjs`: 이 작업 환경의 Chromium으로 화면 검증. Chromium 경로는 환경에 맞게 조정.
- `python3 scripts/package_windows.py`: 공식 Electron 44.3.0 Windows x64 ZIP을 SHA-256 검증 후 패키징.
- `npm run preview`: localhost:4178에서 읽기 전용 화면 확인. 브라우저 미리보기는 계정과 연결되지 않음.
- `artifacts/dashboard-demo.png`: **예시 수치**를 사용한 미리보기.

공식 앱의 소스나 디자인 자산을 복제하지 않은 별도 구현입니다. OpenAI, Anthropic, JoCoding의 공식 앱이 아닙니다.