headroomlabs-ai/headroom

エージェントの費用と待ち時間を膨らませているのは、たいてい人が書いた指示ではなく道具が返してくる出力のほうだ。ログの塊、検索結果の配列、ファイルの中身。同じ形の行が何百と並び、その大半は読み飛ばされる。headroom は、それがモデルに届く前に手元で縮める層を挟む。圧縮は自分のマシンで走り、プロンプトやファイルの中身を外に送って縮めてもらうことはしない、と README に明記されている（ただし、どれだけ縮んだかの統計を送る通信は既定で有効。後述）。

中の仕組みは「種類を見分けてから、種類に合った縮め方をする」という形になっている。まず ContentRouter が中身の型を判定し、JSON なら SmartCrusher、ソースコードなら構文木を見る CodeCompressor、ふつうの文章なら自前の学習済みモデル Kompress-v2-base に振り分ける。JSON の縮め方が特徴的で、キーワードの一覧で残す項目を決めるのではなく、項目ごとのばらつきの統計から、エラーの行・平均から外れた値・配列の先頭と末尾を残す。ログを1万トークンから1,260トークンに縮めても FATAL の行が残る、という実演がトップに置かれている。

もう二つ、実運用側の工夫がある。ひとつは圧縮するのは新しく増えた部分だけという決まり。会話の前半（プロバイダ側のキャッシュが効いている部分）は1バイトも書き換えず、直近の返答や新しく届いた道具の出力だけを縮める。縮めた結果キャッシュが外れて逆に高くつく、という事故を避けるためで、CacheAligner はキャッシュを壊しそうな箇所に印を付けるだけで書き換えはしない。もうひとつは CCR と呼ばれる可逆の仕組みで、元の文章は手元に保存され、モデルが「やはり全文が要る」と思ったときに headroom_retrieve で取り戻せる。使い方は、コードに直接組み込むライブラリ、コードを一切変えずに間に挟むプロキシ、既存のエージェントを包んで起動する headroom wrap、MCP サーバーの4通りが用意されている。

エージェントの請求額が、書いた指示の量と釣り合わないとき

読み込んだファイルやテストの出力が積み上がって膨らんでいるなら、削る先はそこ。コードを触らずにプロキシとして挟めるので、効くかどうかを先に試してから決められる。README には自分の通信量で測り直すコマンドも案内されている。

長時間のエージェント作業で、道具の出力が場所を食っているとき

ログ調査や大きなコードベースの探索のように、同じ形の出力が延々と返ってくる作業が本命。短いやりとり中心なら効果はほとんど出ない、と作者自身が書いている。

「同じ答え」の裏付けは、項目によって強さが違う。 掲載されている精度の検証で、圧縮前と後を並べているのは算数と事実確認の2つだけ（算数は変化なし、事実確認の差は誤差の範囲だと本家も断っている）。読解と道具呼び出しは比較用の元の数字が載っておらず、圧縮率19%・32%の条件でそれぞれ97%、とあるだけだ。下がったのかどうかは、この表からは読み取れない。

削減率（例：障害調査の場面で57%）は繰り返しの多い出力での数字。 自分の使い方で測り直すコマンドが用意されているので、導入の可否はそちらで決めるのが早い。

動作の統計が既定で外に出る。 圧縮率や件数、使っているモデルの名前、OS の種類などを送る通信が既定で有効になっている。プロンプトや生成結果、コード、ファイルの場所は送らないと明記されているが、既定で出ること自体は把握しておきたい。HEADROOM_BEACON=off、DO_NOT_TRACK=1、--offline のいずれかで止められる。

手元でプロセスが動かせることが前提。 圧縮を自分のマシンでやる設計なので、外部プロセスを立てられないサンドボックス環境では使えない、と作者自身が「向かない人」として挙げている。

入れるものが増える点は見ておきたい。 headroom wrap claude は、プロキシを立てるだけでなく、コード探索用の別ツール（Serena）をユーザー全体の設定に登録する。ほかの案件にも残るので、外すには headroom unwrap を実行する必要がある。オプションで切ることもできる。

出力側の削減量は「推定」。 送る側の削減は実測できるが、モデルが書き返す量の削減は「縮めなかった場合」が観測できないため、README でも推定値と幅を示す形になっている。実測したい場合は一部を対照群として除外する設定が用意されている。

ライセンスは Apache-2.0。CLI が入るのは PyPI の配布物だけで、npm 側はライブラリのみという違いがある。