Claude Code 및 Codex 세션을 감싸는 토큰 예산 압축 레이어

What they did

headroom-ai 패키지를 설치하고 `headroom wrap claude`와 `headroom wrap codex`를 사용해 애플리케이션 코드를 전혀 변경하지 않고 기존 에이전트 세션을 포트 8787의 로컬 압축 프록시를 통해 라우팅했습니다. 또한 MCP 서버를 등록해 에이전트가 대용량 도구 출력을 축소하거나 되돌릴 수 있는 CCR 캐시를 통해 원본을 다시 가져오고 싶을 때 `headroom_compress`, `headroom_retrieve`, `headroom_stats`를 직접 호출할 수 있도록 했습니다. 에이전트 자체의 노트를 깔끔하게 유지하기 위해 Serena의 시맨틱 코드 도구와 함께 사용해 심볼 조회와 편집이 전체 파일을 컨텍스트에 쏟아붓지 않고 정밀하게 유지되도록 했습니다. 긴 CI 로그와 대용량 JSON API 응답에 대해 전후 비교를 실행해 FATAL 오류 줄과 특정 필드 값이 압축 후에도 바이트 단위로 그대로 유지되는지 확인했고, `headroom_stats`를 검토해 세션별 토큰 절감량을 확인했습니다.

How it went

로그가 많고 JSON이 많은 턴에서 토큰 사용량이 크게 줄었으며, 압축 후에도 중요한 오류 라인은 그대로 유지되었습니다. wrap/unwrap 흐름은 되돌리기 쉬웠고, MCP 도구 덕분에 에이전트가 항상이 아니라 필요할 때 압축할 수 있었습니다. 설정은 빨랐지만 프록시 포트와 MCP 등록을 제대로 맞추려면 문서를 읽어야 했습니다.

Worth knowing

압축 품질은 콘텐츠 유형에 따라 달라진다. 산문과 코드는 로그와 JSON보다 이점이 적다. 가역 캐시는 로컬에 있으므로 검색은 동일한 머신에서만 작동한다. 에이전트를 래핑하면 세션이 시작되는 방식이 바뀌므로, 팀은 롤아웃 전에 unwrap을 테스트해야 한다. 여기서 독립적으로 검증된 벤치마크 수치는 없다.

Wiring

pip 또는 npm(`headroom-ai`)으로 설치하세요. `headroom proxy --port 8787`로 프록시를 시작하고 에이전트가 이를 가리키도록 하거나, `headroom wrap claude|codex`를 사용해 한 명령으로 실행하고 `headroom unwrap <tool>`로 되돌릴 수 있습니다. 에이전트의 MCP 설정에 MCP 서버를 등록하면 `headroom_compress`, `headroom_retrieve`, `headroom_stats`를 도구로 사용할 수 있습니다. 원본은 검색을 위해 CCR 레이어에 로컬로 캐시됩니다. Serena는 시맨틱 심볼 도구를 노출하는 별도의 MCP 서버로 실행됩니다. 두 서버를 동일한 MCP 설정에 나열할 수 있어, 에이전트는 대용량 출력에는 압축을, 코드 탐색에는 Serena를 선택합니다.

Try it yourself

이 저장소에 Headroom을 설정하겠습니다: headroom-ai 설치, 포트 8787에서 로컬 프록시 시작, Claude Code 및 Codex 세션 래핑. 에이전트가 headroom_compress, headroom_retrieve, headroom_stats를 호출할 수 있도록 MCP 서버를 등록합니다. 그런 다음 큰 CI 로그 하나와 큰 JSON 응답 하나를 압축하고, FATAL 라인과 주요 필드가 바이트 단위로 그대로 보존되는지 확인합니다. headroom_stats에서 토큰 절감량을 보고하고, 래핑 해제 방법을 보여드리겠습니다.