headroom vs graphify: squeeze it or map it?

Part of the reduce Claude Code token usage pillar. This page is the head-to-head: two Python tools with opposite theories of where the waste is.

Is headroom or graphify the better fit?

graphify if your project's knowledge lives outside the source; headroom only if your workload is batch rather than interactive. headroom shrinks the message array before every API call. graphify builds a queryable map of the project — code, documentation, PDFs, images, video — so the agent asks the map instead of reading files. Both are free, both are Python, and neither shows a measurable cost saving on my open long-session benchmark. headroom does worse than that: it finished 53% more expensive than running no tool at all, last of twelve. I run that benchmark and sell a competing tool, so what follows is the mechanism, not the scoreboard.

What does headroom actually do?

It rewrites the conversation window before each call. Python SDK, CLI proxy and MCP server, Apache 2.0, roughly 18.7k stars. CacheAligner moves timestamps and UUIDs out of the static prefix into a non-cached tail; ContentRouter routes content to format-specific compressors via ML detection — JSON, code, text, logs, diffs, HTML; IntelligentContext scores what remains across six relevance dimensions. It is reversible: originals live in a local LRU cache with an injected headroom_retrieve tool and optional BM25 sub-search. Per-workload compression is strong — 92% on code-search results and SRE incident logs, 73% on issue triage — and SmartCrusher samples large JSON arrays at 70–95% while always preserving error lines. The footprint is heavy: Python 3.10+, a 150M-parameter ModernBERT model, Magika content detection, 16 to 50 ms per call.

What does graphify actually do?

It maps the project into a knowledge graph the agent can query. Python, MIT, installed from PyPI, invoked as a /graphify slash command across Claude Code, Codex, opencode, Cursor, Copilot, Aider, OpenClaw and others. Its distinguishing move is what it ingests. Most tools in this category index source code and stop there. graphify takes in documentation, PDFs, images and video as well — which matters in projects where the answer to "why is it built this way" lives in a design document, a scanned specification or a recorded walkthrough rather than in a function body. It also produces a persistent, inspectable artefact: graph.json, plus an HTML view and a Markdown report. The graph can be queried later without re-reading the codebase, and the HTML view means a person can audit the index instead of trusting it blind. That is rarer than it should be. The cost is that indexing is an explicit step you re-run as the project moves, and a stale graph does not fail loudly — it misleads quietly.

How does each one fail?

This is the useful comparison, because both fail, and not alike. headroom fails by spending prompt caching. Caching pays only when the prefix is byte-identical between turns, and cached input is billed at a fraction of fresh input on every major provider. A window rewriter changes the prefix whenever its compression decisions change — which is every turn, because the content changes. The cache misses and you re-pay full price for context you already bought. CacheAligner exists to fight exactly this, which tells you the project sees the risk; on a long interactive loop it is not enough. It has a second failure path: when the compressed version turns out to be insufficient, the model calls headroom_retrieve and pulls the original back. You have then paid for the compressed copy, the original, and the round-trip. graphify fails by not being consulted. A slash command is opt-in: the agent queries the graph only when something steers it there. Add the indexing pass's own cost, and a graph that has drifted from the working tree, and the agent can spend tokens reconciling map against territory. The difference in severity matters. headroom's failure is systematic — it applies on every call. graphify's is situational — it applies when you forget to re-index or never invoke it. One is a multiplier, the other is a missed opportunity.

Which sessions does each one suit?

headroom suits batch work. Long, stable payloads processed once, where the prefix is not being invalidated every turn and 92% off a large JSON blob is the whole story. That is a genuine use case. It is not an agent coding loop. graphify suits document-heavy projects. Regulated work with specifications, consultancy handovers, anything where a PDF or a recorded session holds knowledge the source does not. If your repository is pure code with a thin README, graphify's differentiator does not apply to you and a source-only index will be simpler.

What does neither of them do?

Command output at the boundary. graphify never sees it. headroom compresses it inside the window, after it has already been produced and paid for once.
Re-reads. Same file, four times, four charges. Neither deduplicates.
MCP manifests. Every connected server ships tool definitions before your first message. Neither defers them.
Whole-file reads for editing. A map says which file; a compressor shrinks it and risks the cache.

How to apply this today

Check your cache-hit rate first. If it is high, do not install a window rewriter without measuring before and after. That single number is the whole headroom decision.
Ask whether your project's knowledge is in the source. If yes, graphify's non-code ingestion is not buying you anything. If no, nothing else in this category offers it.
Tie re-indexing to an event, not to memory — a branch switch, a daily run. A stale graph is worse than none.
Measure for a week. Both of these look different at task scale and at week scale, and the week is the one you pay for.

What goes wrong (anti-patterns)

Reading a per-payload compression rate as a session saving. 92% off one blob and 53% more expensive over a session are both true of headroom. Installing a graph you never query. The indexing cost is real and the payoff is zero if the agent never asks. Running both. The graph reduces what enters the window; the compressor then destabilises the prefix the graph just made small. You get both downsides and neither upside. Trusting a stale index. Confident wrong answers cost more than no answer.

See also: