https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor

Claude-Code-Usage-Monitor 상세 설명

1. 소개

Claude-Code-Usage-Monitor는 Claude API 사용자들이 자신의 토큰 사용량을 실시간으로 추적하고, 일일 사용량 한도를 설정하며, 지정된 시간에 사용량을 자동으로 초기화할 수 있도록 설계된 가벼운 Python 스크립트입니다. 이는 API 사용량이 많거나 비용 관리가 중요한 프로젝트에 특히 유용합니다.

2. 설치 방법

스크립트를 로컬 시스템에 설정하는 과정은 간단하며, 다음 단계를 따릅니다.

환경 요구 사항

Python 3.10 이상: 스크립트는 Python 3.10 버전 이상에서 실행되도록 개발되었습니다. 이전 버전의 Python을 사용하는 경우, 호환성 문제가 발생할 수 있으므로 업그레이드를 권장합니다.

종속성

이 스크립트는 환경 변수 로드를 위해 python-dotenv 라이브러리에 의존합니다. 이 라이브러리는 .env 파일에 저장된 API 키와 같은 민감한 정보를 안전하게 관리하는 데 사용됩니다.

설치 단계

리포지토리 클론:
먼저 GitHub에서 프로젝트 리포지토리를 복제합니다. 이는 스크립트 파일을 로컬 컴퓨터로 가져오는 과정입니다.
```
git clone https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor.git
cd Claude-Code-Usage-Monitor
```
git clone 명령은 리포지토리를 현재 디렉토리에 복사하며, cd 명령은 복제된 프로젝트 디렉토리로 이동합니다.
가상 환경 생성 및 활성화:
가상 환경을 사용하는 것은 프로젝트 종속성을 시스템의 다른 Python 프로젝트와 분리하여 충돌을 방지하는 좋은 방법입니다.
```
python -m venv venv
```
이 명령은 venv라는 이름의 새 가상 환경을 생성합니다.
가상 환경을 활성화하려면 운영 체제에 따라 다음 명령 중 하나를 사용합니다:
- macOS/Linux:
```
source venv/bin/activate
```
- Windows:
```
venv\Scripts\activate
```
- 가상 환경이 활성화되면 터미널 프롬프트 앞에 (venv)와 같은 표시가 나타납니다.
종속성 설치:
가상 환경이 활성화된 상태에서, 스크립트가 필요로 하는 모든 Python 라이브러리 (이 경우 python-dotenv)를 설치합니다. 이들은 requirements.txt 파일에 명시되어 있습니다.
```
pip install -r requirements.txt
```
.env 파일 설정:
Claude API 키와 같은 민감한 정보는 소스 코드에 직접 노출하지 않고 .env 파일에 저장하는 것이 좋습니다. 프로젝트의 루트 디렉토리 (즉, claude_monitor.py 파일과 같은 위치)에 .env라는 이름의 파일을 생성합니다. 그리고 다음 내용을 추가합니다:
```
CLAUDE_API_KEY="당신의_클로드_API_키_여기에_입력"
```
반드시 "당신의_클로드_API_키_여기에_입력" 부분을 실제 Claude API 키로 교체해야 합니다.

3. 사용법

설치가 완료되면 스크립트를 실행하고 다양한 옵션을 사용하여 모니터링 동작을 커스터마이징할 수 있습니다.

기본 사용법

uv 도구 설치 시 (권장):
uv는 Python 패키징 도구로, claude-monitor와 같은 스크립트를 시스템 경로에 추가하여 어디서든 실행할 수 있게 해줍니다.
```
claude-monitor  # 기본 Pro 플랜 (~7,000 토큰 한도)으로 모니터링 시작
```
스크립트는 기본적으로 Pro 플랜의 토큰 상한선인 약 7,000 토큰을 기준으로 사용량을 모니터링합니다.
- 종료: 모니터링을 중지하려면 터미널에서 Ctrl+C를 누르면 스크립트가 정상적으로 종료됩니다.
개발 모드 (소스에서 직접 실행하는 경우):
uv를 통해 설치하지 않았거나 개발 목적으로 소스 코드를 직접 실행하려면 다음 명령을 사용합니다:
```
./claude_monitor.py
```

설정 옵션

스크립트는 명령줄 인수를 통해 유연한 설정 옵션을 제공합니다.

플랜 지정 (`--plan`)

Claude API의 다양한 플랜에 맞춰 토큰 상한선을 설정할 수 있습니다.

--plan pro: 기본 Pro 플랜 (~7,000 토큰)
--plan max5: Max5 플랜 (~35,000 토큰)
--plan max20: Max20 플랜 (~140,000 토큰)
--plan custom_max: 이전에 기록된 가장 높은 토큰 사용량에 따라 자동 감지됩니다.

예시:

claude-monitor --plan max5

사용량 초기화 시간 (`--reset-hour`)

매일 토큰 사용량이 초기화되는 시간을 24시간 형식 (0-23)으로 지정할 수 있습니다. 이는 사용량 주기를 특정 시간에 맞추는 데 유용합니다.

오전 3시에 초기화: claude-monitor --reset-hour 3
오후 10시에 초기화: claude-monitor --reset-hour 22

시간대 설정 (`--timezone`)

모니터링이 작동하는 시간대를 설정합니다. 기본 시간대는 Europe/Warsaw입니다. 정확한 시간대 설정을 위해 시간대 데이터베이스 (tz database) 시간대 목록에서 유효한 문자열을 사용하십시오.

미국 동부 시간: claude-monitor --timezone US/Eastern
도쿄 시간: claude-monitor --timezone Asia/Tokyo
UTC: claude-monitor --timezone UTC
런던 시간: claude-monitor --timezone Europe/London

4. 저장된 데이터

Claude-Code-Usage-Monitor는 세션 간에 토큰 사용량 데이터를 지속적으로 저장합니다. 이 데이터는 스크립트가 실행되는 동일한 디렉토리에 .claude_monitor_data.json이라는 파일로 저장됩니다.

`.claude_monitor_data.json` 파일의 샘플 구조:

{
    "daily_usage": 1500,       // 현재 일일 사용된 토큰량
    "last_reset": "2023-10-27T00:00:00+02:00", // 마지막으로 사용량이 초기화된 시각 (ISO 8601 형식)
    "plan_limit": 7000         // 현재 설정된 플랜의 토큰 한도
}

이 파일은 스크립트가 재시작되더라도 이전 사용량 정보를 유지하고, 지정된 초기화 시간에 맞춰 사용량을 재설정하는 데 사용됩니다.