Claude Code의 토큰 절감 도구 rtk와 headroom을 실제로 적용해 본 경험

여러분 안녕하세요!

Claude Code의 토큰 소비를 줄이는 도구로 rtk, headroom, lean-ctx, h5i 등이 있습니다.

공표된 절감률이 모두 커서 궁금하여 이 PC(Windows 11)의 Claude Code 환경에 직접 적용해 보고 시험해 보았습니다.

이번에는 그중 rtk와 headroom 두 가지를 도입하고, lean-ctx와 h5i는 다른 날로 미루었습니다.

도입 전에 각 도구의 공식 리포지토리와 제3자 평가를 조사한 결과, 공표된 절감률에는 그대로 믿기 어려운 과장이 포함되어 있었습니다.

게다가 도입 과정에서는 설정 파일 자동 수정이나 통신 오류 등 몇 가지 문제에 부딪혔습니다.

여기서는 그 경위와 실제로 측정할 수 있었던 절감률을 기록하고자 합니다.

먼저 결론부터 말씀드리겠습니다.

rtk와 headroom 모두 실존하는 도구이며, 작동도 합니다.

다만 공표된 절감률을 그대로 믿으면 기대에 미치지 못합니다.

• rtk의 공표값은 'Bash 출력 60~90% 감소'이지만, 이 PC에서 git status와 git log --oneline -50 두 명령어를 실행한 범위에서는 rtk gain이 보여주는 전체 절감률은 7.9%였습니다.
• headroom의 공표값은 '코딩 에이전트에서 20%'이지만, 최소한의 질문 1회(2 API 호출 분)를 측정했을 때 37.9%였습니다. 다만 이는 시스템 프롬프트 등 질문 내용과 무관한 고정 부분이 대부분을 차지하는 요청에서의 수치이며, 지속적인 에이전트 작업과는 전제가 다릅니다.
• Microsoft Copilot 팀의 엔지니어 Evan Boyle 씨는 X 게시물에서 rtk나 headroom 같은 압축 도구에 대해 '압축 결과는 좋거나 중립적이며, 많은 경우 토큰 소비가 오히려 증가했다. 에이전트에 필요한 정보를 압축이 제거하여 재읽기를 유발하기 때문이다'라고 언급했습니다.

따라서 '넣으면 줄어들 것'이라는 도구가 아니라 '넣어도 늘어날 수 있는' 도구로 신중하게 다룰 필요가 있다는 전제하에 도입을 진행했습니다.

이 PC의 환경은 다음과 같습니다.

• OS: Windows 11(회사 PC)
• WSL: Ubuntu 배포판 설치 완료(도입 작업 시점에서는 Stopped)
• Rust/Cargo: 미설치
• Python: 3.14(C: extbackslash Python314)와 3.13(C: extbackslash Program Files extbackslash Python313) 두 계통
• Node.js: 설치 완료

사전에 네 가지 도구의 실존 여부 및 제3자 평가를 웹 검색 및 WebFetch로 조사한 결과는 다음과 같습니다.

'rtk + headroom의 적층 전략이 최소 노력으로 최대 효과'라는 주장도 보였으나, 상기 제3자 평가와 모순되므로 이 방침은 그대로 채택하지 않았습니다.

대신 다음 방침으로 진행했습니다.

• 일괄 도입하지 않고, 1개 도구씩 활성화하여 동작 확인 후 다음 단계로 넘어간다. 동시에 여러 개를 활성화하면 문제가 발생했을 때 어느 도구가 원인인지 분리하기 어렵기 때문에
• 각 도구 도입 직후에 작은 출력(ls 정도)과 큰 출력(git log, 대용량 파일 Read 등) 모두로 동작을 확인한다.
• 역효과가 의심될 경우 비활성화한다. 해제 명령어를 사전에 준비하여 언제든지 원래 상태로 되돌릴 수 있는 상태를 유지한다.
• 공표 절감률을 그대로 성과처럼 작성하지 않고, 공표값과 실측값을 분리하여 기재한다.
• h5i는 Windows 네이티브 미지원이라 도입할 경우 WSL(Ubuntu) 환경 내로 한정한다.

rtk는 GitHub Releases에서 바이너리를 가져와 PATH에 배치한 후, 다음 명령어로 초기화합니다.

rtk init -g

rtk init -g를 실행하자, ~/.claude/RTK.md의 생성과 ~/.claude/CLAUDE.md에 @RTK.md 참조 추가가 자동으로 이루어졌습니다.

다만 ~/.claude/settings.json에 후킹(hook)을 추가하는 과정은 다음 프롬프트에서 멈췄습니다.

Patch existing C:	extbackslash Users	extbackslash rei.ando	extbackslash .claude	extbackslash settings.json? [y/N]
(non-interactive mode, defaulting to N)

원인은 비대화 실행(파이프 또는 스크립트 경유) 시 확인 프롬프트가 자동으로 'N'으로 처리되는 사양 때문이었습니다.

표시된 JSON 조각을 수동으로 복사하여 Edit 도구로 ~/.claude/settings.json에 추가하여 대응했습니다.

추가 후 내용은 다음과 같습니다.

{
"hooks": {
"PreToolUse": [
...

CI 등에서 자동화할 경우에는 대화 프롬프트에 의존하지 않는 도입 절차(settings.json을 직접 생성하는 등)를 검토하는 것이 좋을 것 같습니다.

참고로 rtk init -g는 ~/.claude/CLAUDE.md의 끝부분에 @RTK.md라는 한 줄을 무단으로 추가합니다.

이번에는 기존 규칙 본문에 영향이 없고 끝부분에만 추가되었지만, 개인의 글로벌 설정 파일을 도구가 무단으로 수정하는 점은 사전에 파악해야 할 동작이었습니다.

도입 전에 CLAUDE.md를 백업해 둔 것이 정답이었습니다.

동일 환경에서 git status와 git log --oneline -50을 rtk 경유와 순수 명령어(raw command)로 비교했습니다.

git log --oneline처럼 출력이 이미 간결한 형태인 경우, rtk의 필터는 대상에 포함하지 않아 압축되지 않았습니다.

rtk 공식에서 제시하는 'cargo test 91.8%, git status 80.8%, find 78.3%' 등의 수치는 rtk가 개별적으로 최적화 로직을 가진 명령어에 한정된 값이며, 'rtk를 설치하면 모든 명령어가 일률적으로 수십 % 감소한다'는 의미는 아님을 알게 되었습니다.

이 두 명령어 실행 시점의 rtk 절감량(gain)은 전체적으로 다음과 같습니다.

RTK Token Savings (Global Scope)
════════════════════════════════════════════════════════════
Total commands: 2
...

샘플 수가 적어 참고치일 뿐이지만, 공시된 값과는 인상이 다릅니다.

settings.json에 PreToolUse 훅을 추가하는 것은 현재 작동 중인 Claude Code 세션에는 반영되지 않으며, 다음 세션 시작부터 유효해집니다.

이번 동작 확인은 rtk를 터미널에서 직접 호출하는 방식으로 진행했습니다.

headroom은 pip으로 설치합니다.

pip install "headroom-ai[all]" --python 3.13

Python 3.14 환경에서는 LiteLLM 미지원(비용 환산 기능만 불가, 압축 자체는 가능)이므로 Python 3.13계를 명시 지정했습니다.

pip install "headroom-ai[all]"을 실행하면 litellm을 통해 torch(122MB), transformers, sentence-transformers, onnxruntime 등이 연쇄적으로 설치되어 의존 패키지 수는 100개를 초과했습니다.

'로컬에서 토큰만 줄이는 가벼운 도구'라는 이미지보다 실제 설치는 무게감이 있었습니다.

회선 및 디스크 용량에 여유가 없는 환경에서는, 순수 pip install headroom-ai(extras 없음)부터 시도하는 것이 안전합니다.

pip install 출력에서 다음과 같은 경고가 나왔습니다.

WARNING: The script headroom.exe is installed in '...\\Roaming\Python\Python313\Scripts' which is not on PATH.

사용자 PATH에 수동으로 추가했습니다.

requests.exceptions.SSLError: HTTPSConnectionPool(host='openaipublic.blob.core.windows.net', port=443):
[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate

원인은 이 PC에 설치된 Norton Antivirus의 HTTPS 검사 기능(SSL 인터셉트) 때문이었습니다.

환경 변수 NODE_EXTRA_CA_CERTS는 이미 Norton 인증서(C:\ProgramData\Norton\Antivirus\wscert.pem)를 가리키도록 설정되어 있었지만, 이는 Node.js용 설정이며 Python(requests/certifi)에서는 참조하지 않습니다.

headroom은 tiktoken의 인코딩 데이터를 시작 시 네트워크를 통해 가져오는 동작이 있어, 그 과정에서 SSL 검증에 실패하고 있었습니다.

우회책으로, Python 측의 certifi 인증서 번들(certifi.where()로 얻을 수 있는 cacert.pem)과 Norton 인증서를 결합한 파일을 만들고, REQUESTS_CA_BUNDLE 환경 변수(및 SSL_CERT_FILE)에서 이를 가리키도록 설정하자 프록시가 정상적으로 시작되었습니다.

백신 프로그램이 HTTPS 검사를 수행하는 환경에서는 Python으로 만든 도구에서 이와 같은 종류의 SSL 오류가 발생할 수 있다는 점은 일반적인 지식으로 남겨둘 가치가 있습니다.

Python 라이브러리로서 headroom.compress()를 단독으로 시도했을 때는, 처음에는 원시 문자열을 전달하여 다음 오류가 발생했습니다.

Compression failed, returning original messages: 'str' object has no attribute 'get'

compress()는 OpenAI Chat Completions 형식의 messages 배열([{"role": "...", "content": "..."}])을 기대합니다.

오류 발생 시 예외를 던지지 않고 압축 전 원문을 그대로 반환하는 페일 세이프 설계가 되어 있어, 인지하지 못하고 사용하면 '압축된 것으로 생각'하지만 실제로는 통과만 하고 있는 상태가 될 수 있습니다.

올바른 형식으로 다시 전달하자 오류는 해소되었지만, 메시지 3개에 500자 남짓한 소규모 입력에서는 압축이 전혀 이루어지지 않아 입력과 출력이 일치했습니다.

headroom 공식 문서에도 '작은 출력은 압축 오버헤드로 역효과가 날 수 있다'는 내용이 있어, 이번 실측 결과가 이를 뒷받침하는 형태가 되었습니다.

headroom wrap claude는 프록시를 시작한 후 claude 명령어 자체를 계속 실행시키는 상주형(常駐型) 래퍼입니다.

지금 작동하고 있는 Claude Code 세션 내에서 실행하면, 세션을 중첩으로 감싸게 되어 뒷정리가 어려우므로, 백그라운드 작업으로 프록시 시작(Starting Headroom proxy on port 8787 Proxy ready)까지 확인한 후, 별도의 세션에서 SSL 인증서 관련 환경 변수(REQUESTS_CA_BUNDLE, SSL_CERT_FILE)를 설정하고, 독립된 터미널에서 headroom wrap claude를 통해 Claude Code를 print 모드(-p)로 실행하여 실제 API를 통한 압축 효과를 측정하려고 했습니다.

HEADROOM WRAP: CLAUDE
API Error: Connection refused -- a firewall or proxy may be blocking it (ConnectionRefused)

프록시 배너 표시까지는 도달했고 시작 자체는 했지만, Claude Code 측이 Anthropic API에 연결을 시도하는 단계에서 거부되었습니다.

이 시점에서는 원인을 특정할 수 없었고, 상주 프록시의 시작 실패, 포트 불일치, Norton 안티바이러스의 방화벽에 의한 프록시 목적지 통신 차단 중 어느 것이 의심되는 상황이었습니다.

headroom proxy를 단독으로 백그라운드 시작하고 headroom doctor로 통신을 확인해 보니 다음 동작을 알 수 있었습니다.

• 시작 직후(수 초 이내): proxy: ✗ fail -- not reachable at http://127.0.0.1:8787
• 몇 초 기다린 후 재실행 시: proxy: ✓ pass -- running at http://127.0.0.1:8787

프록시 로그를 보니, 시작 시퀀스 도중에 LiteLLM이 모델 비용 맵을 GitHub에서 가져오려다가 인증서 오류(SSL 인증서 오류와 동일한 종류)가 발생했고, 로컬 폴백으로 전환될 때까지 127.0.0.1:8787의 LISTEN 시작이 지연되고 있었습니다.

15:13:10 - LiteLLM:WARNING: get_model_cost_map.py:454 - LiteLLM: Failed to fetch remote model cost map from

[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate

headroom wrap claude는 프록시의 시작과 claude 프로세스의 시작을 거의 동시에 진행하고 있어, 시작 완료를 기다리는 구현이 되어 있지 않은 것으로 보입니다.

Connection refused는 프록시가 아직 LISTEN을 시작하지 않은 타이밍에 Claude CLI가 연결을 시도했기 때문에 발생한 레이스 컨디션(race condition)일 가능성이 높다는 결론에 이르렀습니다.

headroom wrap claude를 직접 사용하지 않고, 다음 2단계 절차로 변경하자 회피할 수 있었습니다.

export ANTHROPIC_BASE_URL=http://127.0.0.1:8787
claude -p "1+1は?"

headroom doctor에서 proxy: running 상태임을 확인한 후에 실행하자, Connection refused는 재현되지 않았고 정상 응답(2)이 돌아왔습니다.

프록시의 시작 완료를 기다린 후 연결하는 절차로 하면 회피할 수 있다는 것을 확인할 수 있었습니다.

위 호출 이후, headroom doctor의 savings 항목 및 headroom savings 명령어로 실측값을 확인했습니다.

savings: 1,483 tokens / $0.05 saved lifetime -- last request just now
Today 37.9% saved 40,553 / 107,131 tokens $0.0811
Savings by client: claude-code 2 calls · 40,553 tokens saved

"1+1은?"이라는 최소한의 질문 1회(2 API 호출 분)로, 총 107,131 토큰 중 40,553 토큰(37.9%)이 절감된 계산이 되었습니다.

다만 이는 시스템 프롬프트나 툴 정의 등 질문 내용과 무관한 고정 부분이 대부분을 차지하는 요청에서의 결과이며, headroom의 공칭값인 "20%(코딩 에이전트)"라는 수치와는 전제(단발 질문 vs 지속적인 에이전트 작업)가 다릅니다.

지속적인 에이전트 작업에서의 실측은 별도로 필요합니다.

headroom에는 Claude Code 시작 시 프록시를 자동 시작시키는 메커니즘(headroom install apply)이 있습니다.

Claude Code만을 대상으로(--providers manual --target claude), 기본 preset(persistent-service)으로 실행을 시도했습니다.

Warning: persistent-service is not supported on Windows because the Python runner cannot act as a Windows service. Falling back to persistent-task with Task Scheduler.
エラー: アクセスが拒否されました。
Error: Failed to install deployment 'default': Command '['schtasks', '/Create', '/TN', 'headroom-default-startup', '/XML', '...', '/F']' returned non-zero exit status 1.

persistent-service는 Windows에서 미지원이며, Windows 작업 스케줄러(persistent-task)로 자동 폴백되는 사양이지만, schtasks /Create가 Access is denied로 실패했습니다.

만약을 위해 관련 없는 단순 테스트 태스크에서도 동일한 schtasks /Create 명령을 시도했을 때, 마찬가지로 'Access is denied'가 발생했습니다.

whoami /groups
# BUILTIN\Administrators Alias S-1-5-32-544 Group used for deny only

whoami /groups를 확인한 결과, 이 계정은 BUILTIN\Administrators에 속해는 있지만 'Group used for deny only'(관리자 권한이 명시적으로 거부되는 설정) 상태였습니다.

회사 PC의 그룹 정책으로 인한 제한으로 보이며, headroom 측의 결함이라기보다는 이 단말기 고유의 권한 제약이 원인이었습니다.

~/.claude/settings.json에 대한 쓰기는 발생하지 않았고(실행 전 백업과 완전히 일치), 배포(deployment) 또한 미등록 상태로 부작용은 남아있지 않았습니다(headroom install status에서 확인 완료).

이 환경에서는 작업 스케줄러를 통한 자동 시작이 불가능하므로, 자동 시작은 포기하고 검증 및 이용할 때마다 headroom proxy를 수동으로 실행하는 운영 방식을 채택했습니다.

headroom proxy & # 프록시를 실행 (127.0.0.1:8787)
headroom doctor # "proxy: running"이 될 때까지 기다림 (실행에 몇 초 소요)
export ANTHROPIC_BASE_URL=http://127.0.0.1:8787
...

~/.claude/settings.json의 PreToolUse 훅(rtk hook claude)이 활성화된 상태를 유지한 채, headroom을 통한 호출을 실시했습니다.

rtk gain으로 확인한 결과, 이 세션 중 17개 명령어(rtk read, rtk grep, rtk git status 등)에서 77.3%의 감소가 기록되었으나, claude -p 명령어 자체는 rtk의 압축 대상 목록에 나타나지 않았습니다.

rtk는 Bash 도구가 실행하는 개별 명령어(git status, ls, grep 등)의 출력을 로컬에서 압축하고, headroom은 Anthropic API로의 요청/응답 자체(시스템 프롬프트・대화 기록)를 압축한다는 별개의 레이어에서 작동하며, 이번 검증에서는 상호작용으로 인한 오류나 결함은 확인되지 않았습니다.

이번 검증(rtk・headroom 도입)과는 별개로, ~/.claude.json의 최상위 레벨 mcpServers(전 프로젝트 공통 사용자 설정 스코프)에 serena(uvx --from serena-agent serena start-mcp-server ...)가 등록되어 있어 CONNECTION_CLOSED: Connection closed로 연결 실패 상태였습니다.

구현 계획에는 serena 도입에 대한 언급이 없었고, headroom의 pip install 로그를 확인해도 의존 관계로 들어간 것은 MCP 프로토콜 자체의 Python SDK 패키지(mcp)뿐이며, serena 서버 자체의 설치・등록에 관한 기록은 발견되지 않았습니다.

claude mcp add와 같은 명시적인 등록 명령어 실행 로그도 검증 폴더 내에는 남아있지 않아, 언제・어떤 조작으로 추가되었는지는 이번 조사에서 특정할 수 없었습니다.

이에 대한 대응으로 claude mcp remove serena -s user를 실행하여 사용자 설정 스코프에서 삭제했습니다(headroom은 영향을 받지 않고 Connected 상태였습니다).

다시 활성화하려면 다음 명령어로 재등록할 수 있습니다.

claude mcp add serena -s user -- uvx --from serena-agent serena start-mcp-server --project-from-cwd --context claude-code --open-web-dashboard False

이번 검증을 통해 밝혀진, 공칭값과 이 PC에서의 실측 대응 관계를 정리합니다.

숫자만 보면 headroom의 실측치가 오히려 공칭값을 상회하고 있지만, 전제가 '단발적인 최소 질문'이라는 점에서 지속적인 에이전트 작업과는 조건이 다릅니다.

rtk의 실측치가 공칭값보다 크게 낮은 것은, 공칭값이 rtk가 개별적으로 최적화 로직을 가진 특정 명령어에 한정된 수치이기 때문입니다.

두 경우 모두, 공칭적인 감소율을 그대로 이 PC에서의 효과로 간주하는 것은 위험하다는 것을 알게 되었습니다.

Microsoft Copilot 팀의 지적대로, 압축으로 인해 에이전트에게 필요한 정보가 손실되어 재읽기가 발생하면 토큰 소비는 오히려 증가합니다.

도입할 경우, 1개 도구씩 활성화하여 실제 명령어 및 실제 작업에서의 감소율을 확인하고, 역효과가 의심되면 비활성화하는 운영이 필요하다고 생각합니다.

이번에는 Claude Code의 토큰 절감 도구 중 rtk와 headroom을 실제로 도입하며, 공칭값과 실측의 격차, 그리고 도입 시 발생한 사상과 해결책을 기록했습니다.

비대화 모드에서의 설정 파일 자동 편집 제한, Windows 환경 고유의 SSL 인증서 오류나 작업 스케줄러 권한 문제, 프록시 구동의 레이스 컨디션 등 공식 문서를만 읽고서는 알 수 없었던 실태가 많이 보였습니다.

남은 lean-ctx와 h5i는 이번 방침(1개 도구씩 도입하여 공칭값과 실측을 나누어 기재하는 것)을 따르어 다른 날에 검증할 예정입니다.

마찬가지로 토큰 절감 도구의 도입을 고려하고 계신 분들의 참고가 되기를 바랍니다.

생성 AI를 통한 인프라 코드(IaC) 자동화가 진행되는 한편, 'AI가 생성한 코드의 안전성'이나 'AI 에이전트의 행동 제어'에 불안감을 느끼지 않으신가요?

웨비나에서는 AWS × Claude Code를 활용한 IaC 자동화 실천 사례를 기반으로, AI의 행동을 '사람의 감시'가 아닌 '시스템(메커니즘)'으로 자동으로 제어하는 『AI 에이전트 통제 아키텍처』를 소개합니다.

<추천 대상>

• AWS 등 클라우드 환경에서 IaC (Terraform / AWS CDK 등)을 운영 및 도입하고 있는 엔지니어
• Claude Code 등의 AI 에이전트를 인프라 자동화에 활용/검증하고 싶은 분
• AI 생성 코드의 보안 확보나 거버넌스 자동화 설계 패턴에 관심 있는 분

<개최 일시>

11월 10일(수) 12:00~12:40

<개최 형태>

온라인 세미나 (Zoom 사용 예정 / 날짜 한정 아카이브 배포)

<참가 비용>

무료

<신청 방법>