macOS 화면 가장자리에서 Claude Code와 Codex 사용량을 추적하는 UsageNotch

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

UsageNotch는 macOS 화면 가장자리에 부착되어 Claude Code와 Codex의 API 사용량과 속도 제한 상태를 실시간으로 추적하는 도구이다. 로컬 로그 파일을 직접 파싱하여 네트워크 호출 없이 정보를 표시하며, SwiftUI와 AppKit을 결합한 최적화된 UI로 시스템 자원 점유를 최소화했다. 사용자는 5시간 및 주간 단위의 사용량, 예상 비용, 리셋 카운트다운을 한눈에 확인할 수 있으며, 필요시 OAuth를 통한 실제 계정 데이터 연동도 지원한다.

섹션별 상세

UsageNotch는 macOS 화면 가장자리에 부착되어 Claude Code와 Codex의 API 사용량 및 속도 제한 상태를 실시간으로 표시하는 도구이다. 로컬에 저장된 CLI 로그 파일을 직접 읽어 API 키나 네트워크 호출 없이 사용량을 추적하며, 사용자가 설정한 화면 위치에 따라 탭 형태로 고정된다.

bash

./run.sh

UsageNotch를 빌드하고 즉시 실행하는 명령어이다.

bash

./build/UsageNotch.app/Contents/MacOS/UsageNotch --dump

제공자가 인식하는 사용량 데이터를 확인하는 진단 명령어이다.

성능 최적화를 위해 윈도우 크기를 고정하고 SwiftUI 대신 AppKit 수준에서 클릭 이벤트를 라우팅하여 UI 버벅임을 방지했다. 대용량 로그 파일 처리를 위해 원시 바이트 필터링과 캐싱 메커니즘을 적용하여 첫 실행 이후 수 밀리초 내에 데이터를 갱신한다.

5시간 및 주간 단위의 사용량 링, 예상 비용, 리셋 카운트다운을 제공하며, 사용자가 원할 경우 OAuth 토큰을 통해 Anthropic 계정의 실제 사용량을 조회할 수 있다. 메뉴 바 아이콘이나 우클릭 메뉴를 통해 상세 정보를 확인할 수 있으며, 드래그를 통해 화면 가장자리를 자유롭게 이동할 수 있다.

용어 해설

속도 제한(Rate Limit): — API 서비스가 특정 시간 동안 처리할 수 있는 요청 횟수나 토큰 양의 상한선이다. 이를 초과하면 서비스 이용이 일시적으로 제한되며, UsageNotch는 이 잔여 한도를 추적하여 사용자에게 알린다.
스위프트UI(SwiftUI): — 애플의 선언형 UI 프레임워크이다. UsageNotch는 이 프레임워크를 사용하여 화면 구성 요소를 렌더링하며, 성능을 위해 AppKit과 결합하여 이벤트 처리를 최적화했다.

기술

Claude Code
Codex
Swift
SwiftUI
AppKit

활용 사례

API 사용량 모니터링
개발 도구 상태 관리