Headroom으로 토큰 절약을 빠르게 테스트해보고 싶은 분들을 위해

제가 동작 확인을 완료한 설치 절차를 공유합니다

• Headroom에 대한 자세한 설명은 하지 않습니다

• codex 이외의 AI 도구에 대한 설명은 하지 않습니다. 적절히 갈아 끼워 생각해주세요

• MacBook Pro

• OS: macOS Tahoe 26.5

• 칩: Apple M1

• 메모리: 16GB

Headroom 리포지토리

Headroom에 대해 해설해 주고 있는 기사입니다

python 버전은 3.10 이상이어야 합니다

버전이 부족하더라도 다음 pip install 단계에서 에러가 날 뿐입니다

부족하다면 버전을 업그레이드해 주세요

pip로 설치합니다

pip install "headroom-ai[all]"

.zshrc

파일에 다음과 같은 설정을 추가합니다

export HEADROOM_TELEMETRY=off # headroom 통계 데이터 전송 끔
export PATH="$HOME/.headroom/bin:$PATH" # 동봉된 rtk 명령어를 PATH에 추가

통계 데이터에는 프롬프트가 포함되지 않는다고 하지만, 기업에서 사용한다면 꺼두는 것이 무난할 것입니다

$HOME/.headroom/bin

에는 headroom에 동봉된 rtk 명령어가 있습니다. 이것은 readme에 동봉되어 있다는 기재는 있었지만, 그것을 참조하는 방법에 대해서는 기술되어 있지 않아 스스로 찾아냈습니다.

headroom wrap codex

그 후에는 평소와 같습니다. 이상

headroom wrap을 실행한 프로젝트 및 글로벌의 AGENTS.md에 다음과 같은 문장이 추가되었습니다.

<!-- headroom:rtk-instructions -->
# RTK (Rust Token Killer) - Token-Optimized Commands
When running shell commands, **always prefix with `rtk`**. This reduces context
...
```bash
# Git (59-80% savings)
rtk git status rtk git diff rtk git log
# Files & Search (60-75% savings)
rtk ls <path> rtk read <file> rtk grep <pattern>
rtk find <pattern> rtk diff <file>
# Test (90-99% savings) — shows failures only
rtk pytest tests/ rtk cargo test rtk test <cmd>
# Build & Lint (80-90% savings) — shows errors only
rtk tsc rtk lint rtk cargo build
rtk prettier --check rtk mypy rtk ruff check
# Analysis (70-90% savings)
rtk err <cmd> rtk log <file> rtk json <file>
rtk summary <cmd> rtk deps rtk env
# GitHub (26-87% savings)
rtk gh pr view <n> rtk gh run list rtk gh issue list
# Infrastructure (85% savings)
rtk docker ps rtk kubectl get rtk docker logs <c>
# Package managers (70-90% savings)
rtk pip list rtk pnpm install rtk npm run <script>

Rules

• In command chains, prefix each segment: rtk git add . && rtk git commit -m "msg"
• For debugging, use raw command without rtk prefix
  ...

다음 문장이 추가되었습니다.

--- Headroom MCP server ---

[mcp_servers.headroom]
command = "headroom"
...

스킬 (Skill) 참조 등의 문제로 이전처럼 제대로 작동하지 않는 경우가 늘어난 것 같다.

`AGENTS.md`

를 다시 쓰는 것은 지양했으면 좋겠지만, 프록시 (proxy)를 별도로 실행하도록 설정하면 일단 방지할 수 있을지도 모르겠다.