Log Every Agent Invocation: Building Usage Analytics with Claude Code's Stop Hook and transcript_path

개요

Claude Code의 Stop hook과 transcript_path를 활용하여 에이전트 호출 기록을 로그로 축적하고 사용량 분석을 수행하는 메커니즘을 구축합니다.

주요 내용

* 문제점: 에이전트 정의가 많아지면 사용 빈도와 마지막 사용 시점을 파악하기 어려워지며, 사용되지 않는 에이전트는 컨텍스트 주입에 악영향을 줄 수 있습니다.
* 솔루션: Claude Code 세션 종료 시 발생하는 Stop hook 페이로드에 포함된 transcript_path를 Python으로 읽어 에이전트 호출 정보를 JSONL 형식으로 자동 축적합니다.
* 전체 흐름: 세션 종료 → Stop hook 발생 → stop_hooks_combined.sh가 페이로드 수신 → stop_agent_tracker.sh에 전달 → Python이 transcript를 읽어 JSONL 로그에 추가합니다.
* stop_agent_tracker.sh 구현: Bash 래퍼 스크립트와 인라인 Python으로 구성되며, Bash는 표준 입력을 읽고 환경 변수를 설정하고, Python은 실제 transcript 분석 및 로그 기록 작업을 수행합니다.
* Transcript 분석: message.content에서 type이 "tool_use"이고 name이 "Agent"이며 input에 "subagent_type"이 있는 항목을 에이전트 호출로 식별합니다. "Task" 도구도 name: "Agent"로 기록되므로 subagent_type으로 구분합니다.
* 중복 제거: 동일 세션 내에서 Stop hook이 여러 번 발생할 수 있으므로, session_id와 tool_use_id 조합을 키로 사용하여 이미 기록된 항목은 제외합니다.
* 실행 시간 계산: tool_use 레코드의 타임스탬프와 해당 tool_result 레코드의 타임스탬프 차이를 계산하여 duration_ms로 기록합니다. tool_result가 도착하지 않은 경우 "pending" 상태로 기록합니다.
* 로그 형식: ts, session_id, cwd, tool_use_id, subagent_type, description(300자 이내로 클리핑), duration_ms, status, caller 등의 정보를 포함합니다.
* 사용량 집계: agent-usage-summary.sh 스크립트를 사용하여 JSONL 로그를 기반으로 에이전트별 호출 횟수, 고유 타입 수, 상위 10개 에이전트, 7일간 사용되지 않은 에이전트(0-call) 목록 등을 집계합니다.
* 대시보드 통합: dashboard.sh 스크립트는 agent-usage-summary.sh의 출력을 dashboard.md 파일에 매일 업데이트하여 에이전트 사용 현황을 지속적으로 확인할 수 있도록 합니다.
* 고려 사항: Stop hook의 표준 입력은 한 번만 읽을 수 있으므로 임시 파일 사용, mktemp 실패 시 폴백 메커니즘, session_id × tool_use_id를 사용한 중복 제거, description 필드 길이 제한, tool_result 도착 전 Stop hook 발생 시 처리 등이 중요합니다.

시사점

이 메커니즘은 개발자가 자신의 Claude Code 에이전트 사용량을 투명하게 추적하고, 사용되지 않는 에이전트를 식별하여 코드베이스를 효율적으로 관리하며, 자동화 스택의 성능을 지속적으로 모니터링하는 데 기여합니다.