Claude Code 省 92% token 不用改 prompt：Headroom 把 Context 壓縮做成本地基礎設施
Headroom 不是另一個框架，而是在你的 coding agent 和 LLM 之間加了一層本地壓縮層。tool output、RAG、檔案、歷史通通壓過再送，60-95% 省 token，答案還一樣。
目錄+
如果你的 Claude Code 或 Cursor 每天都在吃掉幾萬 token，卻只為了看一段完整的 tool output 或整份檔案，你不是 prompt 寫得不好——是你的 context 從來沒有被當成基礎設施處理過。
今天釋出的 Headroom v0.27.0 在 GitHub 上已經有 45.5k stars。它做的事很直接：在 agent 和 LLM 之間加一層本地壓縮。真實 workload 實測 92% 省 token，答案還是一樣。
這篇文章給獨立開發者：不用改 prompt、不用換 agent，裝一次就能讓所有工具自動受益。
為什麼你的 agent context 一直在爆炸
一個典型的 coding agent 流程是這樣的：
- 讀整個檔案或多個檔案
- 跑測試、lint、build，拿到完整 stdout/stderr
- RAG 拉回幾十段相似程式碼
- 保留整段對話歷史
這些內容預設全部當成「必須給 LLM 看」的東西送上去。結果就是幾萬 token 輕鬆打過去，只為了讓模型「看清楚」。
獨立開發者最常遇到的情況是：同一個 bug 連續問三次，每次都把整個 codebase 片段再塞一次。或者你開一個新專案，agent 先把整個資料夾掃過一遍，stdout 直接吐幾萬行。錢燒得快，cache 命中率卻很低。
更糟的是，這些重複的內容其實大部分是「我上次已經看過了」。但因為沒有中間層去記住「這段已經壓過、這段可以引用」，你只能每次重頭再來。
這不是 prompt 的問題。這是「context 從來沒有經過基礎建設處理」。
Headroom 把壓縮做成本地一層基礎設施
Headroom 不是框架，也不是另一個 agent。它是放在中間的壓縮層。
你可以用四種方式接入：
headroom wrap claude—— 直接包你的 coding agentheadroom proxy --port 8787—— 零程式碼改動，任何語言都行from headroom import compress—— Python/TypeScript 裡直接呼叫- MCP server —— 給支援 MCP 的 client 用
核心流程只有三件事：
- 偵測內容類型（JSON、程式碼、純文字、表格）
- 用對的壓縮器壓縮
- 把原文存在本地，需要時用
headroom_retrieve拿回來
壓縮是可逆的（CCR），模型不會因為少了細節而答錯。它要細節的時候會自己叫工具拿。
60 秒上手 + 真實數據
pip install "headroom-ai[all]"
headroom wrap claude
# 或
headroom proxy --port 8787
跑完之後直接用原本的流程就行。下面是官方提供的真實 workload 數字：
Headroom 真實 workload token 減少百分比
對應的絕對數字（Before → After）：
- Code search：17,765 → 1,408
- SRE debugging：65,694 → 5,118
- Issue triage：54,174 → 14,761
- Codebase exploration：78,502 → 41,254
準確度在 GSM8K、TruthfulQA、SQuAD、BFCL 上都維持在原本水準或更好。
關鍵概念輕解：ContentRouter、CCR 可逆、cross-agent memory
Headroom 內部有幾個乾淨的元件，理解它們就能知道為什麼它「不是又一個 prompt trick」。
對獨立開發者來說，最實際的問題永遠是：「我今天裝了，明天專案換人、agent 換工具，這層還在不在？」因為 Headroom 是本地 process + 可插拔的 proxy 模式，它不綁定任何單一 agent 的內部狀態。只要你的 Claude Code、Cursor、Aider、Codex 還是走 OpenAI-compatible 或 Anthropic 的 API，這一層就能繼續作用。
- ContentRouter：看到 JSON 就走 SmartCrusher，看到 Python/JS 就走 AST 壓縮，看到普通文字就走模型壓縮。
- CacheAligner：盡量讓前綴穩定，讓 provider 的 KV cache 真正打中。
- CCR：壓縮後原文存在本地，模型需要時呼叫
headroom_retrieve拿回來。對你來說是透明的。
最重要的是：這一層是本地跑的，你的資料不會先送到別人的壓縮 API。
為什麼這件事重要？因為現在大多數 agent 框架都在「怎麼更好地呼叫工具」和「怎麼寫更好的 system prompt」上競爭。Headroom 選擇了另一條路：把「輸入之前先瘦身」這件事變成一個可插拔的本地層。框架可以換、prompt 可以改，這一層只要還在，就持續幫你省。
除了省輸入，還能省輸出
Headroom 後來加了 output token reduction：
- 在 system prompt 後面加一句「be terse, don't restate context」
- 當這一輪只是「工具結果回來繼續做」時，自動把 thinking effort 調低
headroom learn --verbosity會從你過去的 session 學你到底喜歡多簡潔
這些都是 proxy 層做的，你不用改任何 agent 設定。
對 indie 來說，這件事特別有感。因為我們通常不會有專人維護 prompt 模板庫，也不會每天 review token usage dashboard。裝上 Headroom 之後，省 token 這件事就從「我今天有沒有寫好 prompt」變成「我的工具鏈裡有沒有這一層」。後者比較容易持續。
什麼時候該用、什麼時候別用
適合用 Headroom 的情況：
- 你每天都在用 coding agent，token 費用已經開始明顯
- 你同時用多個 agent（Claude + Codex + Cursor），想要共享壓縮後的記憶
- 你需要可逆壓縮，隨時能拿回原始內容
可以先跳過的情況：
- 你只用單一 provider 原生的 compaction，而且對目前 token 量滿意
- 你在完全沒辦法跑本地 process 的沙箱環境
和官方原生 compaction、純 prompt 技巧、或只壓 CLI 輸出的工具比，Headroom 的定位很清楚：本地、可逆、覆蓋所有內容類型、還能跨 agent 共享記憶。
| 方案 | 覆蓋內容 | 本地 | 可逆 | 跨 agent |
|---|---|---|---|---|
| Headroom | tool/RAG/log/檔案/歷史 | Yes | Yes | Yes |
| Provider compaction | 只有對話歷史 | No | No | No |
| 純 prompt 技巧 | 看你自己寫 | Yes | 看你 | No |
這不是 prompt engineering，這是基礎設施
Headroom 證明了一件事：對獨立開發者來說，context 已經大到需要被當成一層基礎建設來處理，而不是每次都靠更聰明的 prompt 去應付。裝一次，之後所有 agent 都自動變瘦。
你現在每天多花的那些 token，有沒有可能是因為缺了這一層？