TL;DR

Headroom, או headroom-ai, הוא שכבת context compression ל-AI agents: הוא יושב בין ה-agent לבין ה-LLM, ודוחס את מה שה-agent קורא — tool outputs, logs, files, RAG chunks והיסטוריית שיחה — לפני שזה נכנס למודל. יצאנו לבדוק אותו לא כ-demo, אלא תחת עומס אמיתי של Claude Code ו-Codex על macOS במשך כ־27 שעות. המסקנה: זה לא "כפתור קסם" ולא כל מספר ב-dashboard אומר את מה שנדמה שהוא אומר. אבל כשהשיחות מתארכות, הקבצים משתנים, וה-agent מתחיל לסחוב context היסטורי כבד — Headroom כן מתחיל להחזיר ערך אמיתי. במיוחד אם אתם נתקלים ב-rate limits, או נופלים מדי פעם ל-pay-per-token.

מה Headroom עושה, ולמה זה בכלל מעניין?

הבעיה ש-Headroom מנסה לפתור מוכרת לכל מי שעובד ברצינות עם coding agents: ה-agent לא "חושב" רק על הפרומפט האחרון שלכם. הוא גורר איתו שכבות שלמות של context: קבצים שהוא קרא, פלטי grep, JSON-ים, logs, diffs, תוצאות בדיקות, snippets מ-RAG, היסטוריית שיחה, tool calls קודמים, ושאריות של דברים שהיו חשובים לפני שעה ואולי כבר לא רלוונטיים.

ב-agent tool-heavy, רוב ה-context הזה אינו prose יפה. הוא הרבה פעמים מבנה טכני חזרתי: JSON, logs, file dumps, search results, traces. לפי הטענה של הפרויקט, חלק גדול מזה הוא boilerplate, והבעיה מחמירה ככל שהשיחה מתארכת: סביב turn 10 כבר אפשר לשלם שוב ושוב על עשרות או מאות אלפי tokens בכל קריאה למודל.

Headroom מציע גישה פשוטה ברעיון, אבל די עמוקה בפרטים: לדחוס את כל מה שה-agent קורא לפני שזה מגיע ל-model.

הפרויקט מתאר את עצמו כ:

"The context compression layer for AI agents"

והמשפט החשוב יותר בעיניי הוא:

"Nothing is thrown away."

זה לא סתם ניסוח שיווקי. זאת הארכיטקטורה.

ארבע הדרכים להריץ אותו

Headroom מגיע באותה pipeline בסיסית, אבל עם כמה נקודות כניסה:

בבדיקה שלנו, העניין המרכזי היה proxy + routing של Claude Code ו-Codex + MCP retrieval.

CCR: ה-escape hatch שהופך compression אגרסיבי לפחות מפחיד

הטריק המרכזי נקרא CCR: Compress-Cache-Retrieve.

הרעיון: Headroom יכול לדחוס באגרסיביות, אבל לשמור את המקור המלא ב-local cache. במקום לשלוח למודל אלפי שורות, הוא יכול לשלוח marker בסגנון:

[1000 items compressed to 20. Retrieve more: hash=abc123]

אם המודל באמת צריך את המידע המקורי, הוא יכול לקרוא ל-headroom_retrieve(hash[, query]), והמערכת מחזירה לו את התוכן המקורי מה-store המקומי.

אנחנו אימתנו את מסלול ה-retrieve הזה hands-on: ה-retrieve החזיר את התוכן המקורי הלא-דחוס. כלומר, לפחות בבדיקה שלנו, זה לא היה "סיכום lossy עם תקווה לטוב", אלא מנגנון הפיך בפועל.

מאיפה זה הגיע?

Headroom נוצר על ידי Tejas Chopra, מהנדס ב-Netflix בלוס גאטוס. חשוב לדייק: זה לא פרויקט רשמי של Netflix, אף שהפרויקט מדווח שהוא בשימוש אצל חלק מהצוותים שם.

המקור די אנושי: לפי הדברים של Chopra ב-Show HN המקורי מ־2026-01-15, הוא בנה את Headroom כי הוא הוציא $200 ביום על agents עם tool calls. הוא גם ניסח היטב את בעיית העלות המצטברת:

"By turn 10, you're paying for 100k+ tokens on every LLM call."

עוד משפט שלו מסביר את design philosophy:

"You can't know which data matters until the model tries to use it."

וזה בדיוק למה CCR שומר את המקור.

ציר הזמן, נכון לנקודת הזמן שסופקה לנו:

הפרויקט גם מצטט הערכות founder מכנס Open Source Summit: כ־$700,000 שנחסכו למשתמשים, כ־200 מיליארד tokens "recovered", וכ־90% מ-agent tokens שהם redundant. אלה לא מספרים מבוקרים, אז צריך לקרוא אותם כ-founder estimates — לא כעובדה פיננסית מאומתת.

מה באמת למדנו

כאן מתחיל החלק החשוב. לא "איך זה אמור לעבוד", אלא מה קרה כשחיברנו את זה ל-Claude Code ול-Codex, עם subscription auth, על macOS, בעבודה אמיתית.

1. ההתקנה היא רב-שכבתית ותלויה בסדר פעולות

הדרך הקלה לטעות עם Headroom היא לחשוב שזה switch אחד.

זה לא.

בפועל, setup מלא כלל ארבע שכבות:

1. proxy daemon שרץ קבוע.
2. routing של Claude Code אל ה-proxy.
3. routing של Codex אל ה-proxy.
4. MCP server עבור headroom_retrieve.

הסדר חשוב. קודם מרימים proxy ומוודאים שהוא חי. רק אחר כך מנתבים כלים אליו.

למה? כי אם מגדירים ANTHROPIC_BASE_URL להצביע אל ה-proxy כשה-proxy למטה, sessions חדשים ייכשלו עם connection refused. זה נשמע ברור בדיעבד, אבל באמצע יום עבודה עם כמה sessions פתוחים, זה בדיוק מסוג הדברים שיכולים להפוך "התקנה מהירה" לבלגן.

החדשות הטובות: Claude Code קורא את ה-env, כולל ANTHROPIC_BASE_URL, פעם אחת בלבד בזמן startup של session. לכן שינוי settings לא מנתב מחדש session שכבר רץ. sessions קיימים המשיכו לדבר ישירות עם provider, ורק sessions חדשים אחרי restart עברו דרך Headroom.

זה property בטיחותי חשוב. hooks, לעומת זאת, כן נטענים מחדש live — אז לא לערבב בין ההתנהגויות.

הגוטצ׳ה של scope ב-Claude

הפקודה:

headroom init claude

נראית כאילו היא מחברת את Claude. בפועל, ב-default scope היא כותבת ל-~/.claude/settings.local.json.

השם הזה מטעה. זה project-local, וזה חל רק על sessions שהופעלו מתוך home dir — לא מתוך תיקיות הפרויקט האמיתיות שלכם.

מה שבאמת רצינו היה:

headroom init --global claude

שימו לב: --global הוא group option, כלומר הוא חייב לבוא לפני subcommand. לא אחרי.

הפקודה הזו כותבת ל-~/.claude/settings.json ומכסה sessions מכל directory.

Codex, לעומת זאת, היה פשוט יותר: routing שלו באמת גלובלי דרך ~/.codex/config.toml.

launchd והפקודות שלא תמיד עושות מה שהן אומרות

ב-macOS נתקלנו בבאג סביב launchd:

headroom install start
headroom install restart

שתיהן קרסו עם:

launchctl kickstart exit 113

כאשר השירות היה unloaded. הסיבה: הן מנסות לעשות kickstart לשירות שכבר bootstrapped, אבל לא מחזירות אותו אם הוא ירד לגמרי.

ה-recovery שעבד:

headroom install remove
headroom install apply

עוד gotcha: headroom unwrap claude עוצר את ה-proxy ומנקה רק את settings.json, אבל מפספס את settings.local.json.

וגם: headroom install apply --providers auto זה ה-default, והוא auto-wires כל כלי שהוא מזהה. אם אתם רוצים רק daemon בלי לגעת ב-Claude/Codex/Cursor וכו׳, השתמשו ב-headroom install apply --providers manual.

2. מספר ה-savings משקר — או לפחות צריך לקרוא אותו נכון

המספר הכי מסוכן ב-headroom perf הוא אחוז ה-reduction headline.

לא כי הוא מזויף, אלא כי denominator שלו נשלט על ידי cache-read tokens, שהם זולים מאוד. התוצאה: הוא יכול להיראות מיקרוסקופי גם כשנחסכת עבודה אמיתית.

במהלך יום השימוש שלנו, ראינו trajectory כזה:

הקריאה הנכונה: savings מצטברים ככל שהשיחה מתארכת וככל שיותר reads הופכים stale.

זה לא מוצר שמראה את הערך שלו בהכרח בחמש דקות הראשונות. להפך: short window עלול להמעיט בערך שלו.

Cache hit rate הוא המלך

הנתון המשמעותי ביותר אצלנו היה cache hit rate. ראינו אזור של 87–91%, עד 91.4%.

וזה מסביר הרבה מההתנהגות של Headroom.

בגרסה 0.27.0, אימתנו hands-on שה-proxy תומך ב:

headroom proxy --mode token
headroom proxy --mode cache

חשוב: אני לא מציג את "token-mode" ו-"cache-mode" כטרמינולוגיה רשמית של הפרויקט. זה פשוט flag אמיתי ב-CLI שבדקנו.

• token מתעדף compression, ועשוי לשכתב prior turns כדי למקסם savings.
• cache מקפיא prior turns כדי לשמר provider prefix-cache hit rate.

וזה הבדל גדול.

אם יש לכם 90% cache hit rate, לפעמים הדבר הכי חכם הוא לא לדחוס יותר מדי. cache reads זולים. cache writes יקרים יותר. שבירת prefix cache יכולה למחוק את החיסכון.

ה-router הכללי כמעט לא היה הסיפור

ציפינו לראות ContentRouter דוחס המון.

בפועל, אצלנו:

זה היה אחד הלקחים החשובים: ה-marketing story הוא "compress everything", אבל ה-production story היה יותר עדין. החיסכון האמיתי הגיע לא מה-compressor הגנרי אלא ממנגנון lifecycle שמבין אילו reads כבר התיישנו.

Read lifecycle: הדבר הכי חשוב שלא מצאנו בדוקומנטציה

מצאנו את זה בקריאת source של ההתקנה, לא בדוקומנטציה הציבורית.

יש config בשם ReadLifecycleConfig, ובו התנהגות מעניינת:

למה לא לדחוס superseded reads? כי זה עלול לשבור Anthropic prompt-cache prefix.

זו החלטה נכונה. אולי פחות מרשימה בגרף compression, אבל טובה יותר לכסף ול-latency.

latency: יש מס

ראינו optimization overhead חציוני יורד מכ־270ms בתחילת השימוש לכ־190ms סביב שעה 27. היו גם spikes של כמה שניות.

זה לא אסון, אבל מרגישים את זה. במיוחד כשעובדים interactive עם coding agent ומצפים לזרימה מהירה.

3. איך וידאנו שזה באמת עובד

החלק הכי פחות נעים בכלי כזה הוא חוסר הוודאות: האם הוא באמת מחובר? האם ה-agent באמת עובר דרך proxy? האם retrieve עובד? האם MCP חי?

כאן היו כמה surprises.

headroom mcp status שיקר לנו

הפקודה headroom mcp status הדפיסה:

✗ No config file

אבל זה היה לא נכון בפועל.

הסיבה: היא בדקה legacy path ~/.claude/mcp.json, בעוד שה-registration האמיתי נמצא ב-~/.claude.json.

הפקודה הנכונה לסמוך עליה הייתה:

claude mcp list

והיא הראתה:

headroom … ✔ Connected

לפי המידע שסופק, זה bug מוכר עם upstream fix שכבר אושר ב-PR #990, כך שסביר שהוא ייעלם בעדכון עתידי. אבל בנקודת הזמן שלנו — זה עלה בזמן ובאמון.

אימות retrieve end-to-end

אימתנו את CCR במסלול פשוט:

curl http://127.0.0.1:8787/v1/retrieve/{hash}

וקיבלנו HTTP 200 עם התוכן המקורי הלא-דחוס.

ה-CCR store היה SQLite מקומי ב-~/.headroom/ccr_store.db.

ראינו retention של 30 דקות, כלומר 1800 שניות. הדוקומנטציה מציינת default של שעה, כלומר 3600 שניות. לכן מבחינתנו נכון לנסח את זה כטווח/config discrepancy: בערך 30–60 דקות, configurable, ולא להניח שה-docs תואמים לכל deployment.

0% retrieval rate זה לא בהכרח רע

headroom perf הציג warning בסגנון:

TOIN has 0% retrieval rate — review CCR integration

זה נראה מפחיד.

בפועל, זה היה false alarm benign. זה counter נפרד בשכבת TOIN, בעוד שה-proxy-level CCR retrieve עבד והחזיר מקור.

יותר מזה: 0% retrieval יכול להיות דווקא סימן טוב. זה אומר שהמודל לא היה צריך למשוך חזרה תוכן דחוס. כלומר לא נגרם נזק context שהכריח אותו "לבקש את המקור".

4. מתמטיקת העלות מתהפכת כשעוברים ל-pay-per-token

אם אתם על Claude subscription, המספרים הדולריים ש-Headroom מדווח הם notional. אתם לא באמת משלמים פר token באותו רגע.

אבל זה לא אומר שאין ערך. הערך הוא rate-limit headroom: להישאר מתחת לחלון שימוש מתגלגל, כדי לא להיחנק באמצע יום עבודה עמוס.

אצלנו, בשלב מסוים, גלשנו לכמה שעות של pay-per-token. ושם החיסכון הפך לכסף אמיתי.

הבעיה: על billing לפי tokens, cache economics שולטים.

כלל האצבע שסיפקנו בבדיקה:

המשמעות: אם compression שובר prefix cache, אתם עלולים להחליף cache reads זולים ב-cache writes יקרים. אצלנו, בכ־8% מהבקשות שבהן cache_write > 2× cache_read, זה יכול היה לעלות כסף בשקט.

לכן, דווקא ב-pay-per-token, --mode cache עשוי לחסוך יותר כסף מ---mode token.

כן, זה אירוני: פחות compression אגרסיבי יכול להיות יותר זול.

אז להשתמש בזה או לא?

התשובה שלי: כן, אבל רק אם אתם נכנסים לזה בעיניים פתוחות.

Headroom שווה בדיקה אם…

אתם עובדים עם coding agents שעות ביום, עם שיחות ארוכות ו-tool calls כבדים. במיוחד אם Claude Code, Codex או Cursor קוראים הרבה קבצים, מריצים הרבה searches, מחזירים logs או JSON, ועובדים על codebase שמשתנה תוך כדי session.

הוא גם מעניין אם אתם פוגעים ב-rate limits ב-subscription, או אם יש לכם fallback ל-pay-per-token. שם כל token שנחסך יכול להפוך או לזמן עבודה נוסף, או לכסף ממשי.

בנוסף, אם אתם בונים agent פנימי, library/proxy/MCP נותנים כמה נקודות אינטגרציה נוחות בלי לנעול אתכם לספק אחד.

הייתי נזהר אם…

אתם עובדים בעיקר בצ׳אט קצר ו-prompt-heavy. לפי ה-claims של הפרויקט, שם החיסכון נמוך יותר — סביב 20–40% — וגם זה צריך למדוד על workload שלכם.

הייתי גם נזהר אם latency interactive הוא קריטי, או אם אתם תלויים מאוד ב-1M context של Claude Code. לפי upstream issue #1158, יש claim ש-routing דרך custom proxy host עלול לגרום ל-Claude Code להפיל את header של context-1m ולחתוך את החלון ל־200k. זה מתואר כהתנהגות של Claude Code, לא bug של Headroom, אבל אם אתם חיים על 1M context — אל תגלו את זה באמצע incident.

ולבסוף: אל תתקינו ב-auto על כל הכלים שלכם בלי להבין מה קורה. install apply --providers auto יכול לחווט יותר ממה שהתכוונתם.

פקודות שהייתי שומר בצד

# installation
pipx install "headroom-ai[all]"
# or
pip install "headroom-ai[all]"

# Run the proxy manually
headroom proxy --port 8787

# לחבר Claude Code גלובלית
headroom init --global claude

# daemon-only, בלי auto-wiring לכלים
headroom install apply --providers manual

# recovery לבאג launchd שבו service unloaded
headroom install remove
headroom install apply

# לבדוק MCP דרך Claude, לא דרך headroom mcp status
claude mcp list

# לבדוק retrieve ידנית
curl http://127.0.0.1:8787/v1/retrieve/{hash}

סיכום

Headroom הוא לא magic compression pixie dust. הוא שכבת infrastructure קטנה שיושבת במקום רגיש מאוד: בין ה-agent למודל. לכן גם ההבטחה וגם הסיכון אמיתיים.

מהבדיקה שלנו, הערך שלו לא היה בגרף יפה של "95% compression" על sample קטן. הערך היה הרבה יותר production-ish: שמירה על cache hit rate גבוה, דחיסה של stale reads, הפחתה מצטברת ככל שה-session מתארך, ויכולת retrieve אמיתית כשהמודל צריך מקור.

הדבר שהכי אהבתי הוא האיפוק: Fresh reads לא נדחסים. Superseded reads לא נדחסים כברירת מחדל כדי לא לשבור cache. זה לא נשמע נוצץ, אבל זו בדיוק ההחלטה שמראה שמישהו פה חשב על העלות האמיתית, לא רק על demo.

הדבר שהכי פחות אהבתי הוא חוויית ההתקנה והאבחון: scope מבלבל ב-Claude, פקודות status מטעות, launchd edge cases, ויותר מדי דרכים להפעיל משהו חצי-מחובר.

השורה התחתונה שלי: אם אתם מפעילים coding agents כבדים, Headroom שווה ניסוי מדוד. לא "תתקינו ותאמינו", אלא תמדדו: cache hit rate, cache writes, latency, saved tokens לאורך יום שלם, retrieval failures, והאם זה באמת נותן לכם עוד שעות עבודה לפני rate limit.

כי בסוף, context הוא לא בחינם. הוא פשוט היה מספיק בלתי נראה כדי שנעמיד פנים שכן.

הערות

• כל הנתונים כאן הם point-in-time סביב 2026-06-24 ועל בסיס headroom-ai גרסה 0.27.0.
• מספרי stars/forks, release count ו-contributors הם הערכות נקודתיות ועלולים להשתנות.
• Claims כמו 60–95% fewer tokens, 70–90% ב-tool-heavy coding/RAG, או 20–40% ב-prompt-heavy chat הם claims של הפרויקט, לא benchmark עצמאי שלנו.
• הערכות כמו $700K saved, 200B tokens recovered, ו־90% redundant agent tokens הן founder estimates, לא נתונים מבוקרים.
• מנגנון Read Lifecycle שתואר כאן אומת על ידינו מקריאת source מותקן, אך לא הופיע בדוקומנטציה הציבורית שסופקה.
• ה-1M context caveat מבוסס על claim ב-upstream issue #1158, ויש לאמת אותו בסביבה שלכם לפני שמסיקים מסקנות production.