claude-usage 사용 가이드

지금 이 컴퓨터에 로그인된 Claude Code 구독 사용량이 얼마나 남았는지 알려줍니다. 5시간 창과 7일 창의 사용률, 리셋 시각, 플랜 이름, 그리고 Fable 같은 모델별 주간 한도까지 한 번에 봅니다.

Claude에게 말로 물으면 됩니다 — "사용량 얼마나 남았어?" 한마디면 됩니다. 브라우저로 대시보드를 열거나 명령을 외울 필요가 없습니다.

⚠️ 이 가이드는 Claude Code 구독(Pro·Max) 사용량에 관한 것입니다. Anthropic API 키로 쓰는 요금은 대상이 아닙니다 — 그쪽은 console.anthropic.com 에서 직접 보셔야 합니다.

---

무엇을 할 수 있나요

하고 싶은 것	이렇게 실행하세요
지금 사용량 확인	/claude-usage 사용량 얼마나 남았어
리셋 시각 확인	/claude-usage 5시간 창 리셋 언제야
모델별 주간 한도 확인	/claude-usage 모델별 주간 한도도 같이 보여줘
무거운 작업 전 안전 확인	/claude-usage 5시간 창이 20% 이하일 때만 알려줘
주간 기준으로 판단	/claude-usage 7일 창이 80% 넘었는지 봐줘

자연어로 "지금 claude 써도 돼?", "클로드 코드 한도 확인해줘"라고 말해도 같은 스킬이 동작합니다.

---

무엇을 보여주나요

조회하면 Claude가 다음을 한 줄로 정리해 말해 줍니다.

• 플랜 — Pro, Max 5x, Max 20x 등 현재 구독 등급
• 5시간 창 — 짧은 주기 한도의 사용률과 리셋 시각
• 7일 창 — 주간 한도의 사용률과 리셋 시각
• 모델별 주간 한도 — Fable 등 특정 모델에만 걸린 별도 주간 한도가 있으면 함께

80%를 넘긴 창이 있으면 Claude가 그것부터 먼저 말해 줍니다. 한도에 걸려 작업이 중간에 끊기는 일을 미리 피하기 위해서입니다.

---

무거운 작업 앞에 "안전장치"로 쓰기

여러 단계를 도는 긴 작업(대규모 리팩터링, 문서 일괄 생성, 장시간 조사)을 시작하기 전에 남은 한도를 먼저 확인해두면, 작업이 반쯤 진행된 상태에서 한도에 걸려 멈추는 상황을 막을 수 있습니다.

이렇게 말하세요:

/claude-usage 5시간 창이 30% 이하면 알려줘. 그때만 이 리팩터링 시작할게

기준을 넘어선 상태면 Claude가 통과시키지 않고 현재 사용률과 리셋까지 남은 시간을 알려 줍니다. 조회 자체가 실패한 경우에도 통과시키지 않습니다 — "모르는 상태"를 "괜찮은 상태"로 취급하지 않기 위해서입니다.

---

시작하기 전에 준비할 것

특별한 설정은 없습니다. Claude Code에 이미 로그인되어 있으면 그걸로 끝입니다.

이 스킬은 Claude Code가 로그인할 때 컴퓨터에 남겨둔 자격증명을 그대로 읽습니다.

• macOS — 키체인의 Claude Code-credentials 항목과 ~/.claude/.credentials.json 파일 둘 다 확인해 더 최신인 쪽을 씁니다. 파일에 폐기된 옛 토큰이 남아 있는 경우가 실제로 있기 때문입니다.
• Windows · Linux — 자격증명 파일만 읽습니다.

인터넷 연결이 필요합니다(사용량은 Anthropic 서버에 물어봅니다).

---

안 될 때

증상	원인 / 해결
"로그인되어 있지 않다"는 안내 (no_credential)	이 컴퓨터에서 Claude Code에 아직 로그인하지 않았습니다. Claude Code를 한 번 실행해 로그인하세요
"자격증명이 만료됐다"는 안내 (token_expired)	토큰 유효기간이 지났습니다. Claude Code를 한 번 실행하면 자동으로 갱신됩니다
"응답 형식이 바뀌었다"는 안내 (bad_response)	Anthropic 쪽 응답 구조가 변경된 경우입니다. 스킬 갱신이 필요하니 제보해 주세요
"네트워크 오류" 안내 (network)	인터넷 연결 또는 방화벽 문제입니다
사용률은 나오는데 이메일이 안 보임	이메일 조회를 생략하도록 요청한 경우입니다. "이메일도 같이 보여줘"라고 말하면 나옵니다

---

팁

• 리셋 시각을 함께 보세요. 사용률이 높아도 곧 리셋이라면 잠깐 기다리는 쪽이 낫습니다.
• 모델별 한도는 따로 찹니다. 전체 주간 창은 여유가 있는데 특정 모델의 주간 한도만 90%인 경우가 있습니다 — 이럴 땐 그 모델을 피하면 됩니다.
• 자격증명은 건드리지 않습니다. 이 스킬은 읽기만 하며, 로그인·토큰 재발급을 대신 해주지 않습니다. 만료되면 안내만 합니다.
• 토큰 값은 절대 출력되지 않습니다. 화면·로그·이슈 어디에도 남지 않도록 고정되어 있습니다.

---

이 스킬이 아닌 것

알고 싶은 것	어디로
Codex CLI(ChatGPT) 사용량	codex-usage 스킬
Anthropic API 키 과금·조직 콘솔 사용량	console.anthropic.com 에서 직접
메뉴 막대에 항상 띄우고 80%·100%에서 알림 받기	sheriff 앱 (같은 데이터의 상주 버전)

---

지금 버전의 범위와 한계

• ⚠️ 버전 0.1.0 (experimental): Anthropic 쪽 응답 구조가 바뀌면 조회가 실패할 수 있습니다. 그때는 조용히 넘기지 않고 "응답 형식이 바뀌었다"고 알려 줍니다.
• 사용량을 조회만 합니다. 한도를 늘리거나 플랜을 바꾸지 않습니다.
• 과거 이력·추세는 다루지 않습니다. 현재 시점의 값만 봅니다.