vole

Vole은 AI 코딩 에이전트를 위한 로컬 우선 사용량, 비용 및 이상 징후 모니터입니다. 여러 에이전트가 동시에 실행되면서 각각 독립적으로 토큰을 소모하지만, 도구 루프에 빠지거나 손상된 API에 대해 재시도하거나 동일한 대규모 컨텍스트를 반복해서 읽는 등의 문제가 발생했을 때 이를 알리지 않는 상황을 해결하기 위해 설계되었습니다. 다른 도구들이 "얼마나 썼는가?"에 답한다면, Vole은 "지금 무엇인가 잘못되고 있는가?"를 묻고 비용 보고를 부수적인 결과로 제공합니다. 데이터 처리 Vole은 도구들이 이미 디스크에 기록하는 로그 파일을 읽습니다. 예를 들어 Claude Code의 ~/.claude/projects/**/*.jsonl, OpenCode의 ~/.local/share/opencode/opencode.db, Codex CLI의 ~/.codex/sessions/**/rollout-*.jsonl, Grok CLI의 ~/.grok/logs/unified.jsonl, 그리고 Cursor, Devin, Antigravity의 로컬 저장소를 읽어 단일 스키마로 정규화합니다. 모든 프로세스는 로컬에서 실행되며 스크래핑, 클라우드 API, 로그인 과정이 없고 프롬프트나 도구 콘텐츠를 저장하지 않습니다. 요청되는 유일한 선택적 권한은 심각한 사고 발생 시 알림을 받기 위한 알림 권한뿐입니다. 지원 도구 및 충실도 정책 도구별로 지원 범위가 다릅니다. Claude Code와 OpenCode는 정확한 토큰과 비용을 제공하며, Codex CLI와 Grok CLI는 정확한 토큰을 제공하지만 공개된 요율은 없습니다. Cursor, Devin, Antigravity는 로컬에 토큰을 기록하지 않으므로 활동 내역으로만 처리됩니다. 프로젝트 정책상 "추정" 단계는 없으며, 토큰 수는 도구의 로그에서 그대로 읽거나 아예 없는 것으로 처리합니다. 토큰이 없는 행은 호출 횟수에는 포함되지만 토큰 및 비용 합계에서는 제외됩니다. 코드 라인 수로 Cursor 토큰을 추정하는 방안은 검토되었으나 명시적으로 거부되었습니다. 앱 기능 메뉴바 항목을 통해 실시간 토큰, 비용 또는 아이콘을 표시하며, 사고가 발생 중일 때는 색상이 변경됩니다. 클릭하면 주요 수치, 스파크라인, 도구별 바가 포함된 패널이 열리며, 대시보드에서 전체 뷰를 확인할 수 있습니다. 핵심 요소는 사고 주석이 달린 타임라인으로, 도구별 토큰을 쌓아서 보여주며 마우스 오버 시 버킷 이름, 토큰 수 및 발생한 사고를 표시합니다. 앱은 자체 컬렉터를 내장하여 직접 시작하고 업데이트하며, 체크섬이 포함된 아카이브 릴리스는 SHA-256 검증 후 번들을 교체하는 원클릭 설치를 제공합니다. 명령줄 및 MCP 앱과 더불어 Vole은 동일한 데이터에 대해 터미널 명령어를 제공합니다: pnpm top(실시간 세션, 컨텍스트 대 윈도우, 분당 토큰, 캐시 카운트다운), pnpm digest(마크다운 형식의 에이전트 사용 요약), pnpm pr(PR 설명을 위한 현재 브랜치 사용량), pnpm statusline, 그리고 stdio MCP 서버인 pnpm mcp가 있습니다. MCP 서버는 vole_summary, vole_live_sessions, vole_session, vole_incidents, vole_breakdown, vole_whatif, vole_digest를 노출하여 에이전트가 자신의 세션 비용이나 Vole의 플래그 여부를 물어볼 수 있게 합니다. 이상 징후 규칙 다섯 가지 규칙이 제공됩니다: billable_burn_spike(10분 윈도우 비용이 해당 세션의 일반적인 윈도우보다 3배 이상 높음), repeat_call_loop(출력이 정체된 상태에서 5분간 45회 이상 호출), error_storm(15분 동안 오류 비율 20% 초과 및 최소 5회 오류), rate_limit_pressure(Codex 쿼터 80% 이상 소비), context_pressure(호출 시 모델 컨텍스트 윈도우의 80% 이상 사용). 베이스라인은 leave-one-out 방식을 사용하여 윈도우를 다른 모든 윈도우의 중앙값과 비교하며, 루프 감지는 생산적인 호출 폭증을 루프로 오인하지 않도록 두 가지 신호를 필요로 합니다. 비용 모델 비용은 리스트 가격 기준의 API 가치(API를 통해 사용했을 때의 비용)로 계산되며, UI에는 구독 플랜이 토큰당 청구되지 않는다는 점이 명시되어 있습니다. 요율은 packages/core/src/data/pricing.json에 저장되며 effective_from으로 버전 관리됩니다. ~/.vole/pricing.json을 통해 설치별로 요율을 덮어쓸 수 있어 릴리스 없이도 모델을 추가할 수 있으며, 요율이 설정되기 전의 데이터는 소급 적용되어 재계산됩니다. 알 수 없는 모델은 0이 아닌 NULL을 반환합니다. 검증 및 테스트 프로젝트는 규칙, 쿼리, 버킷팅 및 신뢰도 불변성에 대한 유닛 테스트를 위해 pnpm test를, 독립적으로 재구현된 비용 공식을 사용하여 저장된 모든 행을 소스 레코드와 대조하는 pnpm verify를 제공합니다. 검증은 합계가 아닌 레코드별로 비교하며, 저장소가 비어 있으면 실패하도록 하여 무의미한 통과를 방지합니다. pnpm seed 명령은 source='seed' 태그가 달린 30일치 합성 이력을 생성하여 실시간 데이터와 별도로 차트로 표시합니다. 빌드 및 제한 사항 소스 빌드에는 Node 22+, pnpm, Xcode 26이 필요하며 macOS 26 arm64에서 테스트되었습니다. pnpm app:bundle로 앱을 빌드하고 실행하거나, 컬렉터와 앱을 별도로 실행할 수 있습니다. 문서화된 제한 사항으로는 로컬 토큰을 기록하지 않는 도구에 대한 낮은 커버리지, is_error가 API 오류만 다루어 error_storm이 과소 집계될 수 있는 점, 일부 도구의 생성 속도가 하한선으로 표시되는 점, 컨텍스트 윈도우가 퍼스트 파티 모델 ID에 대해서만 확인되는 점, Antigravity의 타이밍이 파일 mtime 기반의 근사치라는 점 등이 있습니다. 본 프로젝트는 MIT 라이선스이며, "숫자를 임의로 만들어내지 말 것"과 "모든 컬렉터는 멱등성을 가질 것"이라는 두 가지 리뷰 규칙 하에 기여를 환영합니다.