---
title: "claude-usage"
description: "이 머신에 로그인된 Claude Code 계정의 사용량(5시간·7일 창 사용률, 모델별 주간 한도, 리셋 시각, 플랜)을 저장된 OAuth 자격증명으로 직접 조회한다. \"claude 사용량 얼마나 남았어\", \"클로드 코드 한도 확인해줘\", \"5시간 창 리셋 언제야\", \"지금 claude 써도 돼?\" 같은 요청과 무거운 작업 앞 \"N% 이하일 때만\" 게이트(--max)에 사용한다. API 키 과금은 대상이 아니다. [책임 경계] 본 스킬은 Claude Code 구독 사용량 전담 — itda-dev-support:codex-usage 는 Codex CLI 사용량."
pack: itda-dev-support
slug: claude-usage
status: experimental
tags: ["claude", "claude-code", "usage", "quota", "rate-limit", "subscription", "devtools", "gate"]
---
# 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 쪽 응답 구조가 바뀌면 조회가 실패할 수 있습니다. 그때는 조용히 넘기지 않고 "응답 형식이 바뀌었다"고 알려 줍니다.
- 사용량을 **조회**만 합니다. 한도를 늘리거나 플랜을 바꾸지 않습니다.
- 과거 이력·추세는 다루지 않습니다. 현재 시점의 값만 봅니다.