[Hacker News 요약] Claude Code의 불필요한 토큰 소모를 줄이는 방법: agent_summary 비활성화 스크립트 공개
3
설명
Claude Code는 매 약 30초마다 백그라운드 에이전트의 전체 트랜스크립트를 모델에 다시 전송하여 에이전트 패널의 상태 줄을 업데이트하는 데 상당한 토큰을 소모합니다.
이러한 불필요한 토큰 소모는 2026년 8월 13일 Claude Code 2.1.232 버전부터 기본적으로 활성화되었습니다.
Flamerix AI는 이 문제를 해결하기 위해 `agent_summary` 기능을 비활성화하는 Bun `--preload` 스크립트를 개발하여 공개했습니다.
### 배경 설명
생성형 AI 모델, 특히 Claude Code와 같은 복잡한 AI 개발 환경에서는 효율적인 토큰 관리가 매우 중요합니다. 토큰은 AI 모델과의 상호작용 비용을 직접적으로 결정하며, 불필요한 토큰 소모는 비용 증가뿐만 아니라 응답 속도 저하 및 리소스 낭비로 이어질 수 있습니다. Claude Code의 `agent_summary` 기능은 각 백그라운드 에이전트가 자신의 최근 행동을 3~5단어로 요약하도록 모델에 요청하는 방식으로 작동합니다. 이 요약은 사용자에게 직접 표시되지 않고 에이전트 패널의 상태 줄만 업데이트하는 데 사용됩니다. 그러나 이 과정에서 에이전트의 전체 트랜스크립트가 모델로 전송되며, 이는 상당한 양의 토큰을 소모하게 됩니다. Flamerix AI의 분석에 따르면, 이 `agent_summary` 기능이 Claude Code 전체 API 요청의 약 19.7%를 차지하며, 총 지출의 16.4%를 차지할 정도로 비효율적입니다. 특히 2026년 8월 13일 Claude Code 2.1.232 버전부터 이 기능이 기본값으로 활성화되면서 사용자들의 토큰 소모 부담이 커졌습니다. 이러한 배경 속에서, 개발자 커뮤니티는 이 불필요한 토큰 소모를 줄이기 위한 해결책을 모색하게 되었습니다.
### 문제점: `agent_summary`의 비효율적인 토큰 사용
Claude Code는 약 30초마다 각 백그라운드 에이전트의 전체 트랜스크립트를 모델에 전송하여 에이전트 패널의 상태 줄을 업데이트합니다. 이 과정은 2026년 8월 13일 Claude Code 2.1.232 버전부터 기본적으로 활성화되었으며, 사용자에게 직접적인 이점 없이 상당한 토큰을 소모합니다. Flamerix AI의 분석 결과, `agent_summary` 기능이 Claude Code의 총 API 요청 중 약 19.7%를 차지하며, 전체 지출의 16.4%에 달하는 것으로 나타났습니다. 이는 Opus 모델을 사용하는 경우 특히 두드러지며, 입력 토큰 대비 출력 토큰 비율이 약 9,000:1에 달하는 비효율성을 보입니다. 이러한 문제는 OpenTelemetry export 분석을 통해 DRIM에 의해 처음 감지되었으며, 여러 독립적인 측정에서도 18~26%의 토큰 소모가 확인되었습니다.
### 해결책: `no-agent-summary.js` Bun `--preload` 스크립트
Flamerix AI는 이 문제를 해결하기 위해 약 70줄의 코드로 구성된 Bun `--preload` 스크립트인 `no-agent-summary.js`를 개발했습니다. 이 스크립트는 Claude Code 바이너리를 직접 수정하지 않고, `agent_summary` 타이머가 작동하는 방식을 가로챕니다. 구체적으로, 스크립트는 전역 `setTimeout` 함수를 래핑하여, 요약 타이머 콜백의 소스 텍스트에 특정 앵커(예: `[AgentSummary] Timer fired`)가 포함된 경우 타이머를 실행하지 않고 무효한 핸들을 반환합니다. 이를 통해 `agent_summary` 요청을 효과적으로 차단하면서도 다른 타이머 기능은 정상적으로 작동하도록 합니다. 이 스크립트는 MIT 라이선스로 공개되었으며, GitHub에서 소스 코드를 확인할 수 있습니다.
### 설치 및 구성 방법
사용자는 `no-agent-summary.js` 스크립트를 시스템의 안정적인 위치에 저장한 후, 전역 환경 변수 `BUN_OPTIONS`에 `--preload=<스크립트_경로>`를 설정하여 Claude Code 프로세스가 스크립트를 로드하도록 구성해야 합니다. 영구적인 설정을 위해 `.profile`, `.bashrc`, `.zshrc` 또는 systemd user environment 설정 파일에 `export BUN_OPTIONS` 라인을 추가할 수 있습니다. 또한, `CC_AGENT_SUMMARY_MODE` 환경 변수를 통해 `off` (기본값, 비활성화), `pass` (A/B 테스트용, 타이머 활성화), 또는 기타 값 (경고 후 비활성화)으로 모드를 제어할 수 있습니다. 설치 후에는 `claude daemon stop --any` 명령으로 데몬을 재시작하여 변경 사항을 적용해야 합니다.
### 검증 및 주의사항
스크립트 설치 후에는 `BUN_OPTIONS`와 `CC_AGENT_SUMMARY_LOG` 환경 변수를 설정하고 `claude --version` 명령을 실행하여 스크립트가 정상적으로 로드되었는지 확인해야 합니다. 또한, 백그라운드 하위 에이전트를 실행하고 로그를 확인하여 `agent_summary` 타이머가 억제되었는지 검증할 수 있습니다. Claude Code 업데이트 시에는 스크립트가 계속 작동하는지 재검증하는 것이 중요합니다. 이는 Claude Code의 내부 구현 변경으로 인해 스크립트의 매칭 로직이 무효화될 수 있기 때문입니다. 또한, npm으로 설치된 경우 `--ignore-scripts` 옵션은 Bun이 시작되지 않도록 하므로 스크립트가 작동하지 않습니다.
### 가치와 인사이트
이 스크립트는 Claude Code 사용자들이 불필요한 토큰 소모를 줄여 비용을 절감하고 효율성을 높일 수 있는 실질적인 방법을 제공합니다. 특히, AI 모델의 내부 작동 방식에 대한 깊이 있는 이해를 바탕으로, 공식적인 설정 옵션이 없는 문제를 커뮤니티 주도로 해결했다는 점에서 의미가 있습니다. 개발자는 이러한 커뮤니티 기반의 솔루션을 통해 AI 도구의 사용 경험을 최적화할 수 있으며, 이는 향후 유사한 문제에 대한 해결책 개발에도 영감을 줄 수 있습니다. 또한, `agent_summary`와 같은 기능이 사용자에게 명확한 가치를 제공하지 않으면서도 상당한 리소스를 소모할 수 있다는 점을 시사합니다.
### 기술·메타
* **기술 스택**: Bun, JavaScript
* **라이선스**: MIT
* **버전 정보**: Claude Code 2.1.257–2.1.312 (Linux 기준 테스트 완료), macOS (다른 사용자들에 의해 보고됨)
* **관련 프로젝트**: Flamerix AI의 GitHub 저장소 (https://github.com/flamerix-ai/claude-code-agent-summary-off)
* **공개일**: 2026년 10월 29일 (관련 GitHub Gist 활동 기준)
### 향후 전망
Claude Code의 향후 업데이트에서 `agent_summary` 기능의 토큰 소모 효율성이 개선되거나, 사용자 제어 옵션이 공식적으로 추가될 가능성이 있습니다. 현재 Flamerix AI의 스크립트는 임시방편이지만, 이러한 커뮤니티의 노력은 Anthropic이 사용자 피드백을 반영하여 제품을 개선하도록 유도할 수 있습니다. 또한, 다른 AI 모델 및 플랫폼에서도 유사한 비효율적인 토큰 소모 패턴이 존재할 수 있으며, 이 프로젝트는 이러한 문제를 식별하고 해결하는 데 대한 선례를 제공합니다. `no-agent-summary.js` 스크립트의 지속적인 유지보수는 Claude Code의 향후 버전과의 호환성을 보장하는 데 중요할 것입니다.
📝 원문 및 참고
- Source: Hacker News
- 토론(HN): [news.ycombinator.com](https://news.ycombinator.com/item?id=50284255)
- 원문: [링크 열기](https://gist.github.com/flamerix-ai/c3905705cc4205e5de3011fa2e74efce)
---
출처: Hacker News · [원문 링크](https://gist.github.com/flamerix-ai/c3905705cc4205e5de3011fa2e74efce)
이 글에 대한 한 줄 의견
신고 · 불법·유해·아동 안전(CSAE) 관련 콘텐츠
댓글 0
아직 댓글이 없습니다. 로그인하면 바로 의견을 남길 수 있습니다.