Agent-Blackbox — Claude Code/OpenCode 세션 맵·토큰 낭비 분석 도구

▲ 이미지 출처: GeekNews

AI 코딩 에이전트를 실무에 투입한 팀이라면 한번쯤 마주하는 당혹감이 있다. 같은 작업을 반복 실행했는데 토큰 비용이 2배 차이 나거나, 어느 날 갑자기 월 청구서가 급등한다. 원인을 찾으려 해도 에이전트 세션은 ‘블랙박스’다. Agent-Blackbox는 이 블랙박스를 열어 세션 흐름과 토큰 낭비 패턴을 시각화하는 오픈소스 CLI 도구다. MIT 라이선스로 공개됐으며, npm 한 줄 명령으로 실행된다.

왜 지금 이 도구가 필요한가 — 학술 연구가 먼저 경고했다

Agent-Blackbox의 핵심 동기는 단순한 불편이 아니라 검증된 연구 결과에서 출발한다. 2026년 4월 미시간대·스탠퍼드·MIT 공동 연구팀(Longju Bai 외 7인)이 발표한 논문 “How Do AI Agents Spend Your Money? Analyzing and Predicting Token Consumption in Agentic Coding Tasks”는 에이전트 토큰 소비의 민낯을 드러냈다.

이 연구는 여덟 개 최신 LLM을 SWE-bench Verified 데이터셋 기준으로 분석했는데, 결론이 충격적이다. 첫째, 에이전트 코딩 작업은 단순 코드 추론보다 약 3,500배, 멀티턴 챗보다 약 1,200배 더 많은 토큰을 소비한다. 둘째, 동일한 과제를 반복 실행해도 총 토큰 사용량이 최대 30배까지 차이난다. 셋째 — 그리고 Agent-Blackbox의 출발점이 되는 발견 — 프런티어 모델이 자신의 토큰 사용량을 사전 예측할 때 상관계수가 최대 0.39에 불과하며, 일관되게 실제 비용을 과소 추정한다고 밝혔다.

스탠퍼드 디지털경제연구소가 공동 참여한 이 연구는 공식 발표 페이지에서 핵심 결론을 이렇게 명시한다. “frontier models fail to accurately predict their own token usage (with weak-to-moderate correlations, up to 0.39)” — 즉 에이전트에게 ‘이 작업에 토큰이 얼마나 필요해?’라고 물어봐도 신뢰할 수 있는 답을 얻을 수 없다. 토큰 예산 관리를 모델에 위임할 수 없다는 뜻이다.

Agent-Blackbox의 작동 방식 — 에이전트 자기보고가 아닌 관찰 기반 기록

Agent-Blackbox는 에이전트의 ‘자기보고’를 믿지 않는다. 대신 실행 중 발생하는 실제 이벤트를 관찰하고 기록하는 방식을 택한다. 지원 호스트는 Claude Code, OpenCode, Codex이며, npm 패키지(@taewooopark/agent-blackbox)로 배포된다. 설치는 단 한 줄이다.

npx @taewooopark/agent-blackbox up --host claude-code

실행하면 기본적으로 localhost:5173에 대시보드가 열린다. 도구가 기록하는 이벤트는 파일 읽기·수정, 배시 실행 결과(종료 코드 포함), 검색, 할 일 업데이트, 권한 요청, 서브에이전트 위임, 모델별 토큰 흐름, 재시도 패턴에 이르기까지 11개 컨텍스트 효율 지표를 다룬다. 모든 데이터는 로컬에만 저장되며, API 키나 외부 서버 전송이 없다는 점이 프라이버시 면에서 차별화된다.

세션 맵과 효율 점수 — 무엇을 보여주는가

Agent-Blackbox의 핵심 출력물은 두 가지다. 세션 맵(session map)과 컨텍스트 효율 점수(context efficiency score)다.

세션 맵은 에이전트가 무엇을 읽고, 무엇을 변경하고, 어떤 결정을 내렸는지를 시간 순서로 재구성하는 시각적 그래프다. 도구 개발자는 이를 마크 롬바르디(Mark Lombardi) 스타일의 내러티브 구조 시각화라고 표현한다. 재생(replay) 기능으로 세션의 임의 시점을 스크럽해 당시 상태를 확인할 수 있다.

컨텍스트 효율 점수는 다음 낭비 패턴을 정량화한다. 동일 파일 반복 읽기(redundant reads), 수정 대비 과도한 파일 읽기, 대용량 명령 출력이 컨텍스트를 잠식하는 경우(amplification), 근본 원인 해결 없이 명령을 반복하는 재시도 낭비(retry waste), 그리고 프롬프트 캐시 활용률 저하(low cache utilization)가 주요 항목이다.

성능 개선 효과도 실제 수치로 제시된다. 도구 문서에서 인용하는 사례에 따르면, 동일 작업을 최적화 전후로 비교했을 때 토큰 사용량이 939,000에서 521,000으로 감소하고 효율 점수는 80에서 99로 상승했다. 선택적으로 활성화 가능한 인라인 옵티마이저는 세션 진행 중 반복 읽기를 차이값(diff)으로 대체해 실시간 낭비를 차단한다.

토큰 낭비의 구조 — 왜 에이전트 세션은 비효율적인가

토큰 낭비의 구조적 원인을 이해하면 Agent-Blackbox 같은 도구의 필요성이 명확해진다. Claude Code 토큰 최적화를 다룬 실무 가이드 “Claude Code Token Optimization: 19 Changes to Cut Costs”는 핵심 메커니즘을 이렇게 설명한다. “Every time Claude reads a file, runs a shell command, or calls an MCP server, the full output gets appended to context. Not a summary. The whole thing.” 즉 파일을 읽거나 명령을 실행할 때마다 전체 출력이 컨텍스트에 누적된다. 대화 50번째 메시지는 5번째 메시지보다 처음부터의 전체 내용을 다시 읽어야 하므로 비용이 기하급수적으로 증가한다.

claude-context-optimizer 프로젝트(GitHub, egorfedorov)는 유사한 접근으로 이 문제를 수치화한다. 해당 도구의 실제 세션 데이터에 따르면 “CCO saved you 71K tokens this session (~$0.36). Your 200K budget worked like 271K (1.36x)”라는 결과를 기록했으며, “the average Claude Code session wastes 30-50% of tokens on files that are read but never actually used”라고 주장한다. Agent-Blackbox는 이와 유사한 문제의식을 공유하되, 클라이언트 플러그인이 아닌 독립형 로컬 기록 도구로 접근한다는 점이 다르다.

2026년 3월 Claude Code v2.1.89 업데이트 이후 일부 사용자가 “Max 20 플랜을 리셋 후 70분 만에 소진”했다는 사례가 보고될 만큼, 에이전트 토큰 소비는 예측과 관리가 어려운 문제가 됐다. ClaudeFast 분석에 따르면 커뮤니티는 이미 ccusage, claude-monitor, ccflare, claude-doctor, ccstatusline 등 다섯 개 이상의 독립 모니터링 도구를 자생적으로 만들어냈다. Agent-Blackbox는 이 생태계에서 세션 재생과 구조 시각화에 특화된 포지션을 차지한다.

비교: 기존 모니터링 도구와의 차이

ccusage, claude-monitor 등 기존 도구 대부분은 로컬 JSONL 파일을 파싱해 소비된 토큰 총량과 비용을 사후에 집계하는 방식이다. 유용하지만 ‘어떤 단계에서 얼마를 썼는가’라는 인과 분석에는 한계가 있다.

Agent-Blackbox의 접근은 다르다. 에이전트 실행 중 이벤트를 실시간으로 관찰해 세션의 인과 구조를 재구성한다. 어떤 파일 읽기가 다음 어떤 수정으로 이어졌는지, 어떤 재시도가 불필요했는지, 서브에이전트 위임이 토큰 흐름에 어떤 영향을 줬는지를 추적한다. 과거 실행을 재생할 수 있고, 작업 유형별(리서치/디버그/운영/기능 개발/편집) 아키타입 점수를 산출한다. 핸드오프 익스포트 기능으로 다른 세션에서 이어서 실행하는 것도 지원한다.

제안(suggestion) 기능은 API 키가 필요 없다. 규칙 기반 분석을 기본으로 하며, 원한다면 Ollama나 OpenAI 호환 서버 같은 로컬·무료 모델을 선택적으로 연결할 수 있다. Node.js 20 이상 환경이면 추가 설정 없이 작동한다.

중소기업·개발팀 시사점

• 비용 예측 불가 구조를 직시하라. Bai et al. 연구가 확인했듯 에이전트 스스로 토큰 비용을 정확히 예측하지 못한다(상관계수 최대 0.39). 청구서가 예상을 벗어날 때 원인을 찾으려면 세션 수준의 계측이 필요하다. Agent-Blackbox 같은 도구가 그 출발점이다.
• 같은 작업이라도 실행 방식에 따라 비용이 30배 달라진다. 프롬프트 구조, 파일 읽기 순서, 서브에이전트 위임 방식을 최적화하는 것은 모델 선택만큼이나 중요한 비용 통제 수단이다. 효율 점수가 낮은 패턴을 찾아 반복에서 제거하라.
• 로컬 운영이 핵심이다. 소규모 팀은 외부 분석 서비스에 코드·세션 데이터를 올리기 어렵다. 로컬 기록과 오프라인 제안을 지원하는 도구가 실무적으로 더 안전하다.
• 모니터링 도구도 조합해서 써라. ccusage로 월별 비용을 추적하고, Agent-Blackbox로 세션 내 낭비 패턴을 분석하는 이중 구조가 실용적이다. 하나의 도구가 모든 것을 해결하지 않는다.
• 캐시 활용률을 확인하라. Bai et al. 연구는 캐시 읽기 토큰이 총 비용의 주요 비중을 차지한다고 지적한다. 캐시 히트율이 낮으면 같은 컨텍스트를 매번 재처리하는 비용을 낸다. Agent-Blackbox의 캐시 활용 지표로 이를 즉시 확인할 수 있다.

---