Codex Pet Limit Rings

Codex pet 주변에 남은 용량을 두 개의 링으로 보여주는 작은 macOS companion app.

한줄 요약

codex-pet-limit-rings는 Codex pet를 감싸는 투명 오버레이를 띄워서, 짧은 구간 한도와 주간 한도를 한눈에 보여주는 macOS 보조 앱이다.

핵심 포인트

Codex 앱 자체를 패치하지 않는다.
pet의 위치를 따라다니는 별도 overlay를 사용한다.
어떤 Codex pet이든 동일하게 동작한다.
기본 pet, 커스텀 pet, tiny dog, robot, weather daemon 모두 지원 범위다.
메뉴바 아이콘으로 표시/갱신/종료를 제어한다.

동작 방식

이 프로젝트의 핵심은 companion boundary다.

Codex 앱 번들을 건드리지 않는다.
로컬 Codex 상태를 읽고, 로컬 토큰으로 ChatGPT usage를 조회한다.
투명하고 항상 위에 뜨는 별도 창으로 링을 렌더링한다.
pet이 닫히면 링도 사라지고, pet이 다시 뜨면 따라붙는다.

이 방식은 앱 업데이트에 덜 취약하고, 설치/해제가 비교적 단순하다.

UI가 보여주는 것

바깥 링: short-window limit remaining
안쪽 링: weekly limit remaining
색상: green/blue → amber → red
hover: 현재 endpoint 기준 정확한 퍼센트
menu bar: hide, refresh, quit

설치와 사용

기본 설치:

tools/install-limit-rings.sh

개발 실행:

tools/run-limit-rings.sh

제거:

tools/uninstall-limit-rings.sh

코드/프로젝트 구조

tools/codex-pet-limit-rings.swift — 네이티브 macOS companion app
tools/install-limit-rings.sh — build + install + login item 등록
tools/uninstall-limit-rings.sh — 삭제
tools/run-limit-rings.sh — 개발 실행
tools/build-limit-rings.sh — app bundle builder
skills/codex-pet-limit-rings/SKILL.md — install/debug/validation workflow
docs/limit-rings.md — data flow와 렌더링 계약

데이터와 보안

앱이 보는 것은 로컬 Codex 파일과 usage endpoint뿐이다.

~/.codex/.codex-global-state.json
~/.codex/auth.json
~/.codex/logs_2.sqlite

OpenAI API key는 필요하지 않다.

관련 노트