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 키와 같은 민감한 정보를 안전하게 관리하는 데 사용됩니다.

설치 단계

1. 리포지토리 클론:

   먼저 GitHub에서 프로젝트 리포지토리를 복제합니다. 이는 스크립트 파일을 로컬 컴퓨터로 가져오는 과정입니다.

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

   git clone 명령은 리포지토리를 현재 디렉토리에 복사하며, cd 명령은 복제된 프로젝트 디렉토리로 이동합니다.

2. 가상 환경 생성 및 활성화:

   가상 환경을 사용하는 것은 프로젝트 종속성을 시스템의 다른 Python 프로젝트와 분리하여 충돌을 방지하는 좋은 방법입니다.

   python -m venv venv

   이 명령은 venv라는 이름의 새 가상 환경을 생성합니다.

   가상 환경을 활성화하려면 운영 체제에 따라 다음 명령 중 하나를 사용합니다:

   • macOS/Linux:

     source venv/bin/activate

   • Windows:

     venv\Scripts\activate

   • 가상 환경이 활성화되면 터미널 프롬프트 앞에 (venv)와 같은 표시가 나타납니다.
     

3. 종속성 설치:

   가상 환경이 활성화된 상태에서, 스크립트가 필요로 하는 모든 Python 라이브러리 (이 경우 python-dotenv)를 설치합니다. 이들은 requirements.txt 파일에 명시되어 있습니다.

   pip install -r requirements.txt

4. .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         // 현재 설정된 플랜의 토큰 한도
}

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

5. 기여 방법

이 프로젝트는 오픈 소스이며 모든 종류의 기여를 환영합니다.

• 버그 보고: 스크립트에서 발견한 문제를 GitHub 이슈 트래커에 보고합니다.
• 기능 제안: 개선 사항이나 새로운 기능에 대한 아이디어를 공유합니다.
• 코드 기여: 직접 코드를 작성하여 기능을 추가하거나 버그를 수정하고 풀 리퀘스트를 제출합니다.

6. 라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다. 이는 스크립트를 자유롭게 사용, 수정, 배포할 수 있음을 의미합니다. 자세한 내용은 리포지토리의 LICENSE 파일을 참조하십시오.