CodeLedger: 오픈소스 Claude Code 플러그인이 토큰 사용량과 백그라운드 에이전트를 추적합니다

CodeLedger가 하는 일

CodeLedger는 토큰 사용량, 프로젝트 비용, 백그라운드 에이전트 활동을 자동으로 추적하는 오픈소스 Claude Code 플러그인(MCP 서버)입니다. 이는 Max 20x 플랜에서 8개 프로젝트에 걸친 77개 Claude Code 세션을 분석한 후, 백그라운드 에이전트에 의한 상당한 토큰 소비를 발견하며 만들어졌습니다.

해결하는 문제

Claude Code의 내장 /cost 명령어는 현재 세션 데이터만 보여줍니다. 다음을 확인할 수 있는 기본 방법이 없습니다:

• 프로젝트별 기록
• 에이전트별 분석
• 어떤 백그라운드 에이전트가 소비하는지
• 어떤 작업에 어떤 모델이 사용되는지

터미널을 닫으면 그 내용은 영원히 사라집니다.

분석에서 발견한 주요 결과

• $2,061 상당의 API 비용 (77개 세션, 8개 프로젝트)
• 가장 비싼 프로젝트: 사이드 프로젝트에 $955 상당의 토큰
• 233개 백그라운드 에이전트가 에이전트 토큰 지출의 23%를 소비
• 컴퓨팅의 57%는 Opus가 차지 (파일 검색과 같이 Sonnet으로도 충분히 처리 가능한 작업 포함)
• 한 세션에서 100개 이상의 백그라운드 에이전트가 생성되어 $80 이상의 토큰 가치를 소비

발견된 백그라운드 에이전트 패턴

• acompact-* 에이전트는 대화가 길어질 때 컨텍스트를 압축하기 위해 자동으로 실행되며, 세션에서 사용하는 모델(Opus 포함)을 사용합니다.
• aprompt_suggestion-* 에이전트는 프롬프트 제안을 생성하며 긴 세션에서 자주 생성됩니다.
• JSONL agentId 접두사를 분석하지 않고는 "내가 요청한 에이전트"와 "시스템 백그라운드 에이전트"를 구분할 수 있는 기본 방법이 없습니다.

CodeLedger 기능

• 모든 세션에 걸친 프로젝트별 비용 추적
• 어떤 에이전트가 가장 많은 토큰을 소비했는지 보여주는 에이전트별 분석
• 오버헤드 감지 — 코딩 에이전트와 백그라운드 acompact-*, aprompt_suggestion-* 에이전트 구분
• 모델 최적화 권장 사항
• 대화형 질의 — "이번 주에 프로젝트 X에 얼마를 썼나요?"와 같은 질문 가능

작동 방식

• SessionEnd 이벤트에 연결하고 로컬 JSONL 파일을 분석합니다.
• 백그라운드 스캐너가 훅이 활성화되지 않은 세션을 포착합니다.
• 모든 것을 로컬 SQLite 데이터베이스(~/.codeledger/codeledger.db)에 저장합니다 — 클라우드 사용 없음, 원격 측정 없음.
• MCP 도구 노출: usage_summary, project_usage, agent_usage, model_stats, cost_optimize

설치

npm install -g codeledger

이 도구는 아직 Anthropic Marketplace 승인을 기다리고 있지만, npm 설치로 직접 사용할 수 있습니다.