loplop-h/spent

Claude Code 세션의 실제 비용을 확인하세요.

효율성 점수. 생산적 사용 vs 낭비된 사용 분석. 실시간 터미널 대시보드.

당신은 매일 Claude Code를 사용합니다. 각 세션의 비용이 얼마나 드는지 알고 있나요? 어떤 도구 사용이 생산적이고 어떤 것이 낭비인지 알고 있나요?

spent는 모든 도구 사용(tool use)을 추적하고, 이를 생산적(productive), 중립적(neutral), 또는 낭비(wasted)로 분류하여 효율성 점수를 제공합니다. API 키는 필요 없습니다. 외부 서비스도 필요 없습니다. 모든 것은 Claude Code 자체의 훅(hook) 시스템을 통해 로컬에서 실행됩니다.

pip install spent
spent cc setup # Claude Code 훅 설치 (1회)
spent cc live # 사이드 터미널에서 대시보드 열기

그게 전부입니다. spent cc setup은 ~/.claude/settings.json에 세 가지 훅을 설치합니다:

• PostToolUse: 모든 도구 호출(Edit, Read, Bash, Grep 등)을 기록합니다.
• SessionStart: 세션이 시작되는 시점을 표시합니다.
• Stop: 세션 종료를 표시하고 최종 요약을 작성합니다.

설정 후 Claude Code를 재시작하세요. 그 시점부터 비용이 자동으로 추적됩니다.

기능	상태
세션별 비용 추적	완료
실시간 터미널 대시보드 (spent cc live)	완료
도구별 비용 분석	완료
세션 기록 및 트렌드	완료
웹 대시보드 (spent cc dashboard)	완료
효율성 팁	완료
Claude Code 스킬 (/spent)	완료
상태 표시줄(Statusline) 통합	완료
JSON 내보내기	완료
멀티 모델 가격 책정 (Opus, Sonnet, Haiku)	완료

Claude Code 훅은 모든 도구 사용 시 실행됩니다. spent는 각 이벤트를 ~/.spent/claude-sessions.jsonl에 있는 로컬 JSONL 파일에 다음 내용과 함께 기록합니다:

• 타임스탬프 (Timestamp)
• 도구 이름 (Edit, Read, Bash, Grep, Glob, Agent 등)
• 입/출력 글자 수 (Input/output character counts)
• 세션 ID (Session ID)
• 모델 식별자 (Model identifier)

이 로그를 바탕으로, spent는 토큰 수(글자 수 / 4, 여기에 대화 길이에 따라 증가하는 컨텍스트 오버헤드 추가)를 추정하고 Claude 모델 가격 책정을 사용하여 비용을 계산합니다:

모델	입력 (1M 토큰당)	출력 (1M 토큰당)
Opus	$15.00	$75.00

API 호출은 없습니다. 네트워크 요청도 없습니다. 모든 것은 훅 데이터를 통해 로컬에서 추정됩니다.

# Setup (한 번만 실행)
spent cc setup # 훅(hooks) + 상태 표시줄(statusline) 설치
# 실시간 모니터링
...

모든 도구 사용(tool use)은 다음 세 가지 카테고리 중 하나로 분류됩니다:

생산적 (Productive)
코드를 생성하거나 작업을 진전시키는 동작.

Edit/Write/MultiEdit -- 작성되거나 수정된 코드
Agent -- 작업 위임 (task delegation)
Bash -- 성공한 명령 (에러 표시가 없는 경우)

중립적 (Neutral)
정보 수집. 필요하지만 직접적으로 생산적이지는 않음.

Read/Grep/Glob -- 파일 검색 및 읽기
TodoRead/TodoWrite -- 작업 관리 (task management)
WebSearch/WebFetch -- 리서치

낭비 (Wasted)
토큰을 소모했지만 작업을 진전시키지 못한 동작.

Bash (에러 출력 포함) -- 실패한 명령, 스택 트레이스 (stack traces)
Read (60초 이내에 동일한 파일 읽기) -- 중복 읽기
Edit (다른 Edit 이후 30초 이내에 동일한 파일 수정) -- 급격한 재수정 (보통 실수를 바로잡는 경우)

효율성 점수(efficiency score)는 가중치가 적용된 공식입니다:

score = ((productive * 1.0) + (neutral * 0.5) + (wasted * 0.0)) / total * 100

70점 이상이면 양호합니다. 40점 미만은 많은 시간이 실패한 시도와 재작업(re-work)에 소모되고 있음을 의미합니다.

spent는 Claude Code 세션 내에서 직접 사용할 수 있는 /spent 스킬을 포함합니다:

/spent # 현재 세션 비용 및 효율성 표시

spent가 설치되어 있으면 이 스킬을 자동으로 사용할 수 있습니다. 이 스킬은 동일한 JSONL 로그를 읽어 Claude Code 세션을 떠나지 않고도 포맷팅된 요약을 표시합니다.

• 모든 데이터는 사용자의 머신 내 ~/.spent/에 유지됩니다.

• 외부 API 호출 없음, 텔레메트리(telemetry) 없음, 네트워크 요청 없음

• 훅 스크립트(Hook scripts)는 비동기 셸 명령(async shell commands)으로 로컬에서 실행됩니다.

• JSONL 로그에는 도구 이름, 글자 수, 타임스탬프만 포함됩니다 -- 파일 내용, 프롬프트(prompts), 코드는 포함되지 않습니다.

• 비용 이상 탐지 (Cost anomaly detection) -- 세션이 평소보다 빠르게 토큰을 소모할 때 알림을 보냅니다.

• 팀 대시보드 (Team dashboards) -- 팀원 전체의 비용을 집계합니다.

• CI 사용 보고서 (CI usage reports) -- PR당 비용, 브랜치당 비용을 산출합니다.

• 세션 비교 (Session comparison) -- 세션 간의 효율성을 비교합니다.

• 사용자 정의 분류 규칙 (Custom classification rules) -- 사용자가 직접 생산적/낭비적 규칙을 정의할 수 있습니다.

• 알림 임계값 (Notification thresholds) -- 세션 비용이 제한을 초과할 때 알림을 보냅니다.

기여를 환영합니다. 가이드라인은 CONTRIBUTING.md를 참조하세요.

git clone https://github.com/loplop-h/spent.git
cd spent
pip install -e ".[dev]"
...

MIT