この記事について
Headroomでトークン節約を手っ取り早く試したい方向け
自分が動作確認できたインストール手順の共有です
この記事で取り扱わないこと
- Headroomの細かな説明はしません
- codex以外のAIツールの説明はしません。適宜読み替えてください
確認環境
- MacBook Pro
- OS: macOS Tahoe 26.5
- チップ: Apple M1
- メモリ: 16GB
参考
Headroomリポジトリ
Headroomについて解説してくださっている記事です
1. Pythonのバージョン確認
pythonのバージョン3.10以上である必要があります
バージョンが足りなくても次のpip installで落ちるだけです
足りなければバージョンアップしてください
2. Headroomインストール
pipでインストールします
pip install "headroom-ai[all]"
3. 環境変数の設定
.zshrcファイルなりに以下の設定を追加します
export HEADROOM_TELEMETRY=off # headroom統計データ送信オフ
export PATH="$HOME/.headroom/bin:$PATH" # 同梱のrtkコマンドをパスに追加
統計データにはプロンプトは含まれないそうですが、企業で使うならオフにしておくのが無難でしょう
$HOME/.headroom/binにはheadroomに同梱されているrtkコマンドがあります。これはreadmeに同梱されていることの記載はありましたがそれの参照方法について記述が無く、自力で見つけました。
4. headroomの実行
headroom wrap codex
後は従来どおり。以上
おまけ
補足: headroom wrapを実行すると設定ファイルが一部書き換わります
AGENTS.md
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
usage by 60-90% with zero behavior change. If rtk has no filter for a command,
it passes through unchanged — so it is always safe to use.
## Key Commands
```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
- `rtk proxy <cmd>` runs command without filtering but tracks usage
<!-- /headroom:rtk-instructions -->
.codex/config.toml
以下の文章が追記されました
# --- Headroom MCP server ---
[mcp_servers.headroom]
command = "headroom"
args = ["mcp", "serve"]
# --- end Headroom MCP server ---
# --- Headroom proxy (auto-injected by headroom wrap codex) ---
[model_providers.headroom]
name = "OpenAI via Headroom proxy"
base_url = "http://127.0.0.1:8787/v1"
supports_websockets = true
# --- end Headroom ---
所感
スキルの参照とかで以前の用にうまく動かないことが増えた気がする
AGENTS.mdを書き換えるのはやめてほしいけどproxyを別で立ち上げるようにすれば一応防げるかも