cc-usage

A terminal monitor that mirrors Claude Code's /usage tab. Shows your current 5-hour session window, weekly limits (all models and Sonnet-only), and extra usage credits — and auto-refreshes every minute so you can keep it open in a spare terminal.

Claude Code Usage

Current session
███████▌                                            14% used
Resets 4pm (America/Toronto)

Current week (all models)
███████████                                         22% used
Resets Apr 24 at 8am (America/Toronto)

Current week (Sonnet only)
█▌                                                  3% used
Resets Apr 24 at 8am (America/Toronto)

Updated 11:23:45 · Next refresh in 47s · [r] refresh · [q] quit

Features

• Pixel-matches the styling of Claude Code's /usage view (same 9-step block characters, same fill/empty colors).
• Reads the OAuth token from macOS Keychain — no extra setup if you're already signed in to Claude Code.
• Live mode polls every 60 seconds with jitter; keeps the last known data on transient network errors.
• Also supports --once for scripts/pipes.

Requirements

• macOS (reads the Claude Code OAuth token from the system Keychain)
• Node.js 20+
• Claude Code installed and signed in with a Pro, Max, or Team subscription (claude auth status should say loggedIn: true)

Installation

npm install -g @yyongpil/cc-usage

That puts the cc-usage command on your PATH.

Installing from source

git clone https://github.com/yyongpil/cc-usage.git
cd cc-usage
npm install
npm run build
npm pack
npm install -g ./yyongpil-cc-usage-0.1.0.tgz

Usage

cc-usage                 # live mode, refreshes every 60s
cc-usage --interval=30   # custom refresh interval (seconds, min 5)
cc-usage --once          # print once and exit (good for pipes/scripts)
cc-usage --no-color      # disable ANSI colors
cc-usage --help
cc-usage --version

Keys (live mode):

Key	Action
r	Refresh immediately
q	Quit
Ctrl+C	Quit

When stdout is not a TTY (e.g. piped to a file), cc-usage automatically falls back to --once so it doesn't spam ANSI codes into logs.

How it works

Claude Code's /usage tab calls GET https://api.anthropic.com/api/oauth/usage with an OAuth bearer token and the anthropic-beta: oauth-2025-04-20 header. This tool does the same call:

1. Reads the OAuth access token from macOS Keychain (security find-generic-password -a "$USER" -s "Claude Code-credentials").
2. Sends the request.
3. Renders the response (five_hour, seven_day, seven_day_sonnet, extra_usage) as progress bars.

The token is cached in memory for the process lifetime and only re-read if the server returns 401 (at which point cc-usage will ask you to run Claude Code once to refresh it).

Troubleshooting

Not logged in to Claude Code. Run 'claude auth login' first. The Keychain entry isn't there. Install Claude Code and sign in.

OAuth token rejected. Run 'claude' once to refresh, then try again. Your access token expired. Open Claude Code (it refreshes the token on startup), then re-run.

Bars show 0% used with unfamiliar field names. Anthropic changes the response shape occasionally. Open an issue with the output of cc-usage --once (redact the values if you prefer).

Disclaimer

This is an unofficial tool. It depends on an undocumented Anthropic endpoint that Claude Code uses internally, so it can break without warning when Claude Code updates. Not affiliated with Anthropic.

License

MIT © Yongpil Yoon

---

cc-usage (한국어)

Claude Code /usage 탭을 터미널에 그대로 띄워주는 모니터. 현재 5시간 세션 사용량, 주간 사용량(전체 모델 / Sonnet 전용), Extra usage 크레딧을 1분마다 자동으로 갱신하며 보여줍니다. 남는 터미널 창에 띄워두고 작업하기 좋아요.

Claude Code Usage

Current session
███████▌                                            14% used
Resets 4pm (America/Toronto)

Current week (all models)
███████████                                         22% used
Resets Apr 24 at 8am (America/Toronto)

Current week (Sonnet only)
█▌                                                  3% used
Resets Apr 24 at 8am (America/Toronto)

Updated 11:23:45 · Next refresh in 47s · [r] refresh · [q] quit

특징

• Claude Code /usage와 동일한 스타일 (9단계 유니코드 블록 문자, 동일한 fill/empty 색상).
• macOS Keychain에서 OAuth 토큰을 읽어오기 때문에 Claude Code에 이미 로그인되어 있다면 추가 설정 없이 바로 동작합니다.
• 라이브 모드는 60초 간격으로 폴링하고(지터 ±5초), 일시적 네트워크 오류 시에는 마지막으로 성공한 데이터를 계속 보여줍니다.
• 스크립트/파이프용 --once 모드도 지원.

요구 사항

• macOS (Claude Code OAuth 토큰을 시스템 Keychain에서 읽음)
• Node.js 20 이상
• Claude Code 설치 + Pro / Max / Team 구독 로그인 상태 (claude auth status 가 loggedIn: true로 나와야 함)

설치

npm install -g @yyongpil/cc-usage

이러면 cc-usage 명령이 PATH에 등록됩니다.

소스에서 설치

git clone https://github.com/yyongpil/cc-usage.git
cd cc-usage
npm install
npm run build
npm pack
npm install -g ./yyongpil-cc-usage-0.1.0.tgz

사용법

cc-usage                 # 라이브 모드 (60초마다 자동 갱신)
cc-usage --interval=30   # 갱신 간격 변경 (초, 최소 5)
cc-usage --once          # 1회 출력 후 종료 (파이프/스크립트용)
cc-usage --no-color      # ANSI 색상 비활성화
cc-usage --help
cc-usage --version

단축키 (라이브 모드):

키	동작
r	즉시 새로고침
q	종료
Ctrl+C	종료

stdout이 TTY가 아니면(파일로 리다이렉트 등) 로그 파일에 ANSI 코드가 쌓이지 않도록 자동으로 --once 모드로 전환됩니다.

동작 원리

Claude Code /usage 탭은 OAuth bearer 토큰과 anthropic-beta: oauth-2025-04-20 헤더로 GET https://api.anthropic.com/api/oauth/usage를 호출합니다. 이 도구도 동일하게 동작합니다.

1. macOS Keychain에서 OAuth 액세스 토큰을 읽음 (security find-generic-password -a "$USER" -s "Claude Code-credentials").
2. 위 엔드포인트에 요청.
3. 응답(five_hour, seven_day, seven_day_sonnet, extra_usage)을 프로그레스 바로 렌더링.

토큰은 프로세스 메모리에 캐시되고, 서버가 401을 돌려줄 때만 재조회합니다 (그 경우 Claude Code를 한 번 실행해 토큰을 갱신하라고 안내).

문제 해결

Not logged in to Claude Code. Run 'claude auth login' first. Keychain에 엔트리가 없습니다. Claude Code를 설치하고 로그인하세요.

OAuth token rejected. Run 'claude' once to refresh, then try again. 액세스 토큰이 만료됐습니다. Claude Code를 한 번 실행해 토큰을 갱신한 뒤 다시 실행하세요.

바가 0% used로만 뜨거나 낯선 필드가 보인다면 Anthropic이 응답 스키마를 바꿨을 수 있습니다. cc-usage --once 출력을 이슈에 올려주세요 (값은 가려도 됩니다).

면책 고지

비공식 도구입니다. Claude Code가 내부적으로 쓰는 문서화되지 않은 Anthropic 엔드포인트에 의존하므로, Claude Code 업데이트와 함께 예고 없이 동작이 멈출 수 있습니다. Anthropic과 관련 없는 개인 프로젝트입니다.

라이선스

MIT © Yongpil Yoon