Usage – Claude, Codex, Antigravity, Grok용 실시간 할당량 모니터

기능 개요

usage는 여러 AI 코딩 어시스턴트(Claude Code, Codex, Google Antigravity, Grok CLI)의 토큰 할당량 한도를 모니터링하고 macOS 메뉴 바 또는 Windows 시스템 트레이에 남은 %를 표시하는 데스크톱 유틸리티입니다. 표시기는 할당량이 줄어들수록 녹색 → 노란색 → 빨간색으로 색이 변하며, 클릭하면 세부 분석, 장애 알림, 빠른 작업이 포함된 작은 패널이 열립니다.

대상 사용자

• 일상 코딩 워크플로에서 Claude Code, Codex, Antigravity 또는 Grok을 정기적으로 사용하는 개발자.
• 리팩터링 도중 할당량이 재설정되어 당황하지 않도록 하려는 사용자.
• 브라우저나 로그 파일을 열지 않고 남은 AI 어시스턴트 예산을 빠르게 시각적으로 확인해야 하는 팀.

작동 방식(개요)

1. 데이터 소스 – 앱은 Claude Code, Codex, Grok, Muse Code가 머신에 기록하는 로컬 로그 파일을 읽습니다. Antigravity의 경우 Antigravity CLI가 저장한 OAuth 토큰을 사용하여 Google의 공식 할당량 엔드포인트를 호출합니다.
2. 메뉴 바/트레이 UI – 작은 아이콘이 현재 세션/주별 할당량 비율을 색상으로 구분해 표시합니다. 클릭하면 프로젝트별 토큰 수, 비용 추정치, 장애 배너가 포함된 패널이 확장됩니다.
3. Claude Code 통합 – 선택 사항인 상태 표시줄 훅을 Claude Code 안에 설치할 수 있습니다. Claude 창 하단에 한 줄 요약이 추가되고 추가 헬퍼(사이드 패널, 토큰 절약, 초보자 모드 등)를 활성화할 수 있습니다.
4. 보고서 및 테마 – 앱은 토큰 추세와 비용에 대한 오프라인 HTML/CSV 보고서를 생성할 수 있으며 16가지 시각적 테마 중에서 선택할 수 있습니다.
5. CLI 모드 – Linux 또는 헤드리스 사용의 경우 uvx usage-cli(또는 uv tool install usage-cli)를 실행하면 터미널 UI가 실행되고 다른 도구(Starship, tmux, 사용자 스크립트)가 사용할 수 있는 usage status --json 명령을 제공합니다.

주요 기능

기능	표시/작업 내용	중요성
할당량 모니터	녹색-노란색-빨간색 아이콘에 백분율 표시. 클릭하면 세션, 주별, 프로젝트별 분석을 볼 수 있습니다.	즉각적인 시각적 피드백으로 예상치 못한 할당량 소진을 방지합니다.
Antigravity & Grok 카드	Gemini 풀 사용량 또는 Grok 주간 크레딧을 Claude/Codex와 함께 표시.	모든 AI 코딩 예산을 한곳에서 관리할 수 있습니다.
장애 알림	Claude, Claude API 또는 Codex API 상태 페이지에서 문제가 보고되면 빨간 배너를 표시.	실패한 요청을 기다리는 대신 작업을 일시 중지할 수 있습니다.
컨텍스트 및 캐시 경고	컨텍스트 창이 가득 차면 상태 표시줄이 /clear 또는 /compact를 권장합니다.	큰 프롬프트에 낭비될 토큰을 절약합니다.
Claude Code 사이드 패널	편집기 옆에 할당량, 다른 대화, 백그라운드 작업을 표시.	컨텍스트 전환을 줄이고 여러 채팅을 동시에 모니터링할 수 있습니다.
진행 컨시어지	새 세션을 시작할 때 마지막 요청, 커밋되지 않은 변경 사항, 미완료 TODO를 AI가 상기합니다.	수동으로 요약할 필요가 없어 시간과 토큰을 절약합니다.
토큰 절약	코드는 정확하게 유지하면서 Claude/Codex에 더 짧고 간결한 답변을 요청합니다.	저자 측정에 따르면 평균 응답 길이를 약 40% 줄입니다.
초보자 및 할당량 인식 모드	기술 용어 설명과 할당량 초과 경고를 제공.	초보자와 예산을 의식한 작업에 유용합니다.
HTML 보고서	일일/주간 토큰 추세, 비용, 프로젝트 순위, "연간 리뷰" 히트맵을 표시. HTML, CSV, PNG로 내보내기 가능.	AI 사용량과 예산을 오프라인으로 분석할 수 있습니다.
16가지 시각적 테마	클래식, 매트릭스, Windows 95, 신문 등.	데스크톱 스타일에 맞게 외관을 맞춤 설정할 수 있습니다.
크로스 플랫폼	macOS(메뉴 바)	Windows(시스템 트레이)

설치 및 시작하기

• macOS – brew install --cask aqua5230/usage/usage(권장) 또는 최신 릴리스에서 .app zip을 다운로드합니다.
• Windows – usage-windows.zip을 다운로드하여 압축을 풀고 usage.exe를 실행합니다. Edge WebView2가 필요합니다(대부분의 Windows 10/11에 내장되어 있음).
• Linux / 기타 OS(터미널 전용) – uvx usage-cli(영구 설치 없음) 또는 uv tool install usage-cli로 영구 usage 명령을 설치합니다.
• 첫 실행 후 팝오버에서 Set Up Status Line을 클릭하여 Claude Code 훅을 설치합니다(또는 소스에서 해당 명령을 실행). 이후 Claude Code/Codex를 재시작하세요.

제한 사항 및 고려 사항

• 앱은 로컬 로그만 읽습니다. 로그를 지우면 과거 데이터를 잃게 됩니다.
• Antigravity 할당량은 네트워크 액세스와 저장된 OAuth 자격 증명이 필요합니다. 그렇지 않으면 카드가 숨겨집니다.
• 초보자 모드와 할당량 인식 모드는 용어 설명을 가져오기 위해 Claude에 요청을 하나 보냅니다. 약간의 추가 할당량 비용이 발생합니다.
• Linux에서는 UI가 터미널 버전으로 제한됩니다. 전체 메뉴 바/트레이 UI는 macOS/Windows 전용입니다.
• 모든 비용 추정치는 내장된 모델 가격표를 사용하며 오프라인으로 계산됩니다.

빠른 시작 체크리스트

1. 플랫폼에 맞는 앱을 설치합니다.
2. 로그가 생성되도록 Claude Code, Codex, Antigravity 또는 Grok 세션을 한 번 이상 실행합니다.
3. 메뉴 바/트레이 아이콘을 열고 Set Up Status Line을 클릭하여 Claude 통합을 활성화합니다.
4. 원하는 시각적 테마를 선택합니다.
5. (선택 사항) 설정 패널에서 초보자 모드 또는 할당량 인식 모드를 켭니다.
6. 셸이나 tmux 구성에서 usage status --json을 사용하여 다른 곳에서 숫자를 참조하려면 사용합니다.

---

위의 모든 세부 사항은 프로젝트의 README에서 직접 가져온 것이며 추가 기능은 추측되지 않았습니다.