사용량 한도

ccam usage는 각 계정이 5시간 한도와 주간 한도를 얼마나 썼는지, 각 구간이 초기화되기까지 얼마나 남았는지 보여 줍니다. 긴 작업을 시작하기 전이나 Claude Code가 한도가 가까워졌다고 알릴 때 실행해, 어느 계정에 여유가 남았는지 확인하세요. ccam statusline은 Claude Code의 상태 표시줄 명령입니다. Claude Code 안에 계정 이름과 사용량을 표시하고, ccam usage가 쓸 수 있도록 수치를 저장합니다.

사용법

ccam usage                  # every account, once
ccam u                      # the same, shorter
ccam usage --watch          # redraw every 60 seconds until Ctrl+C
ccam usage --watch=10       # redraw every 10 seconds
ccam usage -v               # add per-model weekly limits and the data source
ccam usage --json           # machine-readable, one object per account
ccam usage --source cache   # saved numbers only, no network
ccam usage --refresh        # also renew expired logins of accounts not running
ccam statusline install     # set the status line in every account's settings.json

$ ccam usage
 Account     5-hour        Resets    Weekly        Resets    As of
 1 personal  ░░░░░░░░   0% -         ██████░░  70% 2d 16h    9h 36m ago (cached)
 2 work      ██░░░░░░  24% 2h 29m    ███░░░░░  41% 3d 11h    just now (cached)
 3 side      login expired, run `ccam side` once to refresh
→ Most headroom: personal   (open it with ccam next --auto)

터미널에서는 표가 바로 나타나고 각 행에 fetching…이 표시되며, 계정이 응답하는 대로 해당 행을 다시 그립니다. As of는 수치를 가져온 지 얼마나 되었는지 나타내고, (cached)는 엔드포인트가 아니라 저장된 파일에서 가져온 수치라는 뜻입니다. 마지막 줄은 5시간 사용량이 100% 미만인 계정 중 가장 낮은 계정을 알려 주며, 계정이 둘 이상일 때만 나타납니다. 로그인되지 않은 계정은 not logged in → ccam login <name>, API 키 계정은 no limits (API)로 표시됩니다.

ccam statusline install을 실행하면 Claude Code에 [work] · Opus · 5h 24% · 7d 41% 같은 줄이 표시됩니다.

옵션

--source에 다른 값을 주면 --source must be live or cache로 실패합니다. ccam usage는 인자를 받지 않습니다.

ccam statusline은 표준 입력으로 Claude Code의 상태 표시줄 JSON을 읽습니다. 옵션은 --wrap <command> 하나뿐이며, 기존 상태 표시줄 명령을 지정하면 그 출력의 첫 줄 앞에 계정 이름을 붙입니다. ccam statusline install은 옵션을 받지 않습니다. 두 명령 모두 --dry-run을 주면 --dry-run is not supported by `ccam statusline`; nothing was changed를 출력하고 거부합니다.

동작 방식

수치의 출처는 두 곳입니다. 하나는 각 계정 자체의 로그인 정보로 호출하는 Anthropic의 비공개 사용량 엔드포인트 GET https://api.anthropic.com/api/oauth/usage이고, 다른 하나는 Claude Code가 상태 표시줄 명령에 넘기는 값입니다. 관련 코드는 모두 internal/usage에 있습니다.

1. cli.usageCmd가 config.toml을 읽고 계정마다 usage.Account를 하나씩 만듭니다. 여기에는 계정 폴더 ~/.local/share/ccam/profiles/<name>/, 세션 폴더(실행 중인지 확인용), 제자리에 가져온 계정인지 여부가 들어갑니다.
2. Fetcher.FetchAll이 계정마다 고루틴을 하나씩 시작합니다. 모든 고루틴이 http.Client 하나를 공유하므로 엔드포인트 연결이 재사용됩니다. 연결에는 최대 2초, 계정마다 전체 3초가 주어집니다. 리디렉션을 따라가면 토큰이 다른 곳으로 다시 전송되므로 클라이언트는 리디렉션을 따르지 않으며, 응답은 최대 1 MB까지만 읽습니다.
3. 계정마다 처리가 끝나는 대로 그 행을 다시 그립니다. 실패하거나 제때 응답하지 않은 계정은 저장된 수치로 대신하므로, 느린 계정 하나 때문에 다른 계정이 늦어지지 않습니다.

각 계정은 자체 고루틴에서 엔드포인트에 요청하며, 시간 초과된 계정은 대신 저장된 수치를 보여 줍니다.

personal과 work는 제때 응답해 실시간 수치를 보여 줍니다. side는 3초보다 오래 걸리므로, fallback()이 두 캐시 파일을 읽어 가장 나중에 기록된 것을 씁니다. usage.Table()이 행을 그리고, usage.Best()가 마지막 줄에 표시할 계정을 고릅니다.

계정 하나에 대해 Fetcher.Fetch는 다음 순서로 확인합니다.

1. --source cache이면 바로 fallback()으로 갑니다.
2. --no-cache가 없으면, ~/.local/state/ccam/usage/<name>.json에 있는 실시간 결과가 60초(CacheTTL)보다 최근이면 그대로 반환합니다. ccam usage를 연달아 두 번 실행해도 요청은 계정당 한 번입니다.
3. readCredentials()가 .credentials.json(또는 macOS 키체인)을 바꾸지 않고 읽으며, claudeAiOauth 키만 해석합니다. 구독 로그인이 없으면 not logged in이고, .claude.json에 API 키가 있으면 no limits (API)입니다.
4. 만료된 액세스 토큰은 쓰지 않습니다. --refresh가 없으면 그 계정은 만료 표시와 함께 저장된 수치를 보여 줍니다.
5. 그렇지 않으면 ccam이 엔드포인트를 호출합니다. 401이나 403은 로그인 만료로, 그 밖의 상태 코드나 읽을 수 없는 본문은 오류로 처리하며, 둘 다 저장된 수치로 대신합니다.
6. 정상 응답은 측정 시각과 함께 <name>.json에 기록합니다.

fallback()은 <name>.json과 <name>.statusline.json을 모두 읽고 더 최근 것을 씁니다. 저장된 수치를 보여 주기 전에 각 구간의 초기화 시각을 확인해, 수치를 저장한 뒤 초기화된 구간은 0%로 표시합니다. 이전 사용률은 더 이상 맞지 않기 때문입니다. 위 예시에서 personal이 초기화 시각 없이 0%로 표시되는 이유가 이것입니다.

엔드포인트의 응답 형식은 두 가지입니다. 새 형식에는 session(5시간), weekly_all, weekly_scoped(모델별) 항목이 담긴 limits 배열이 있습니다. 이전 형식에는 five_hour, seven_day, seven_day_opus, seven_day_sonnet 객체가 있습니다. ParseLive는 둘 다 읽습니다. limits 배열을 우선하고, 배열이 다루지 않는 부분은 이전 형식의 객체로 채웁니다. 한도가 하나도 없는 본문은 형식이 바뀐 것으로 보고하며, ccam doctor가 이를 알려 줍니다.

토큰 갱신

리프레시 토큰은 갱신할 때마다 바뀝니다. 갱신하면 새 리프레시 토큰을 받고 이전 토큰은 무효가 됩니다. 같은 계정으로 Claude Code가 실행 중일 때 ccam이 로그인을 갱신하면 그 세션은 로그아웃됩니다. 그래서 ccam usage는 --refresh를 주지 않는 한 토큰을 읽기만 하고 절대 쓰지 않습니다. 이 옵션을 주면 Fetcher.refresh는 다음과 같이 동작합니다.

1. ccam import로 제자리에 등록한 계정은 거부합니다. ccam이 모르는 사이에 일반 claude가 그 로그인을 쓸 수 있기 때문입니다.
2. macOS 키체인에 저장된 로그인은 거부합니다.
3. 잠금 파일 $XDG_RUNTIME_DIR/ccam/profile-<name>.refresh.lock(이 변수가 없으면 ~/.local/state/ccam/locks/ 아래)을 잡아, 두 ccam 프로세스가 같은 토큰을 두 번 갱신하지 않게 합니다.
4. 잠금을 잡은 상태에서 그 계정의 세션이 실행 중이면 거부하고, 다른 프로세스가 이미 토큰을 갱신했으면 요청을 건너뜁니다.
5. 리프레시 토큰을 토큰 엔드포인트에 보내고, 새 토큰을 fsutil.AtomicWrite로 .credentials.json에 다시 기록합니다. 파일의 다른 키는 모두 그대로 둡니다.

상태 표시줄 수집기

Claude Code는 상태 표시줄 명령을 실행하면서 JSON 문서를 파이프로 넘깁니다. ccam은 여기서 모델 이름과 rate_limits를 읽습니다.

1. runStatusline은 ccam이 Claude Code를 시작할 때 설정하는 CCAM_PROFILE로 계정을 찾고, 없으면 CLAUDE_CONFIG_DIR를 계정 폴더와 대조해 찾습니다.
2. ParseStatusLine이 rate_limits.five_hour와 rate_limits.seven_day를 읽습니다. API 키 계정이거나 세션의 첫 응답 전이면 JSON에 사용량 한도가 없으며, 이때는 아무것도 저장하지 않습니다.
3. SaveStatusLine이 ~/.local/state/ccam/usage/<name>.statusline.json을 기록합니다. 엔드포인트가 응답하지 않으면 ccam usage가 이 파일을 씁니다.
4. ccam은 [name] · model · 5h N% · 7d N%를 출력합니다. --wrap을 주면 같은 입력으로 sh -c를 통해 지정한 명령을 실행하고, 대신 [name] 뒤에 그 명령의 첫 줄을 붙여 출력합니다.

감싼 명령에는 2초가 주어집니다. 그 시간이 지나면 명령을 종료하고 계정 이름만 표시하므로, 느린 명령 때문에 Claude Code 상태 표시줄이 멈추지 않습니다.

ccam statusline install은 각 계정의 settings.json에 statusLine을 기록합니다. 계정에 이미 상태 표시줄 명령이 있으면 ccam은 그 명령을 --wrap '<old command>'로 보존합니다. 그룹을 통해 공유되는 settings.json은 링크를 거쳐 한 번만 기록되므로, 그룹의 모든 계정에 적용됩니다. 다시 실행하면 이미 ccam을 쓰는 파일에는 (already set)를 출력합니다.

안전장치와 예외 상황

• ccam usage는 --refresh를 주지 않는 한 토큰 파일을 절대 바꾸지 않습니다. 로그인이 만료되었으면 ccam <name>으로 그 계정을 한 번 실행하세요. Claude Code가 갱신합니다.
• --refresh는 실행 중인 계정, 가져온 계정, 키체인 로그인을 절대 건드리지 않습니다. 갱신이 거부되면 저장된 수치와 그 이유를 보여 줍니다.
• 사용량 엔드포인트는 공개 문서가 없고, 바뀔 수도 있습니다. 바뀌더라도 저장된 수치는 계속 볼 수 있으며, ccam doctor가 형식 변경을 보고합니다.
• 저장된 수치도 없고 응답도 없으면 그 행에 lookup failed:와 이유를 표시합니다(예: --source cache일 때 no saved usage).
• 캐시 파일에는 사용률과 초기화 시각만 들어 있으며, 토큰은 절대 들어 있지 않습니다.

관련 문서

• 사용량 한도와 계정 전환
• 다음 계정으로 전환
• 사용량 한도 대응 가이드
• 명령어