Headroom — what we copied, and does it actually work?

There are TWO things called "headroom". You adopted a piece of one into ork (#2264). Here's exactly what, and where it breaks.

Headroom external product

headroomlabs.ai — a transparent proxy between your agent and the LLM. Compresses tool output 70–95%.

  • ● CacheAligner — KV-cache prefix reuse
  • ● ContentRouter — AST-aware per-type compressors
  • ● IntelligentContext — importance-scored fitting
  • ● Reversible: stash original, retrieve on demand
  • ● Runs as headroom proxy --port 8787

ork headroom what WE copied (#2264)

A Claude Code hook (mcp-output-transform) that adopts ONLY the simplest, highest-value piece.

  • ✅ Reversible stash — copied (the core idea)
  • ✅ Content-addressed (sha256) + 7-day TTL
  • ✅ Secret-skip (no credentials to disk)
  • ▱ CacheAligner — not copied
  • ▱ AST routing / importance scoring — not copied

The one mechanism ork copied: reversible head+tail truncation

1 · big MCP output
8,000 chars from mcp__memory__read_graph
zzzz…[8000]…zzzz
→
2 · stash original
full text written to disk, content-addressed
~/.claude/state/orchestkit/
headroom/bc9d580ae187.txt
→
3 · model sees head+tail+pointer
1,800 chars + a Read pointer — nothing lost
zzz…
[Truncated 8,000→1,800. Read …txt for the 6,200 between.]
…zzz

How we check it — the verification ladder

A copied feature is verified by its tests + a direct run, not by hoping it fires live.

1 · Unit / integnpx vitest …headroom-store… …mcp-output-transform…✅ 48/48 pass
2 · Hook standalonepipe a >2K payload to the hook → truncates, stashes, writes pointer✅ works
3 · CC fires it LIVEreal mcp__ call → check mcp-transforms.jsonl for a row with a real session_id❌ 0 rows / 4 restarts

⚠️ Where it breaks — layer 3 only

Installed (plugin 8.25.1) ✓ · env ORK_HEADROOM_REVERSIBLE=1 armed ✓ · hook registered under PostToolUse mcp__* ✓

BUT every live mcp__memory__read_graph comes back full & unlogged. CC 2.1.168 never invokes the hook on live MCP output (ref #1794 — applying updatedMCPToolOutput). It's a Claude Code limitation, not a flaw in what ork copied.

✅ Want working live compression today? Use the proxy.

ork's copy rides a CC hook → blocked by CC. The external Headroom does the same reversible compression but as a transparent proxy — no CC hook, so it can't be blocked the same way:

headroom proxy --port 8787  →  point your agent at it  →  70–95% savings, live.

Meanwhile RTK (the thing you actually use daily) is fixed and saving tokens right now — that win is already in hand.