Three open-source tools — Caveman, Headroom, and Graphify — are often mentioned together as a token-cost stack for AI coding agents, but each one targets a structurally distinct source of waste. Caveman conditions the model's output voice, Headroom compresses the context arriving at the model, and Graphify replaces ad-hoc file reads with structured graph queries. Because they sit at different points in the request lifecycle, a developer can in principle run all three at once without one stomping on another. This article walks through where each tool lives in the request pipeline, why the composition works in theory, and which overlaps still produce diminishing returns in practice. It is aimed at engineers already running a Claude Code or Codex-style agent who are evaluating whether to add one, two, or all three of these tools to a single workflow.
Although Caveman, Headroom, and Graphify are routinely grouped as a "token-cost stack," each one targets a structurally distinct source of waste in an agent's request lifecycle. Treating them as interchangeable is what leads to confusion about diminishing returns when they are layered.
Caveman conditions the output voice of the model. The default agent voice adds articles, hedging, meta-commentary, and tool-use narration that downstream consumers rarely need. Caveman's skill file instructs the model to answer in terse "caveman-speak" while leaving code, commands, and exact error strings untouched. Reported effects include roughly65% fewer output tokens on average (range 22–87% across benchmarks) and ~46% fewer input tokens when used to compress memory files such as CLAUDE.md (Caveman README).
A March 2026 arXiv paper cited in Caveman's documentation, Brevity Constraints Reverse Performance Hierarchies in Language Models, reports that constraining large models to brief responses improved accuracy by 26 percentage points on certain benchmarks — that is, brevity can remove the surface where verbose models talk themselves into wrong answers (AI for Developers).
Headroom compresses the context arriving at the model rather than the model's reply. A ContentRouter inspects each payload and dispatches it to a specialised compressor:
CacheAligner stabilises prompt prefixes so that provider KV caches continue to hit after compression, and compression is reversible: originals are stored locally and the model can retrieve them on demand (Headroom repository).
Graphify attacks a third source of waste: repeated file re-reads. Instead of letting an agent open raw files from scratch on every session, it precomputes a queryable knowledge graph whose traversals return small subgraphs rather than full file bodies. A shipped example indexes 52 mixed files into 285 nodes, 340 edges, and 53 communities, reducing an average query from ~123k tokens of naive file reads to ~1.7k tokens of graph traversal — the widely cited 71.5× figure (Graphify site). Token cost scales with subgraph size, not raw file size.
The decision rule for composing them follows directly from that distinction. Caveman targets visible output prose, Headroom targets structured context payloads, and Graphify targets repeated exploration cost. Because the underlying waste is non-overlapping, the three sit at different points in the request lifecycle, which is the precondition for any meaningful layering — and which of them actually applies in a given session depends on where the bottleneck is.
A typical agent request flows through five stages: retrieval, context assembly, pre-send, provider call, and response. Each of the three tools sits at a different stage, which is what makes the layered stack viable in principle — no two tools compete for the same hook point.
Graphify occupies the earliest stage. It writes a CLAUDE.md note plus a PreToolUse hook on Claude Code, AGENTS.md entries on Codex, and .cursor/rules/ entries on Cursor. Together these artifacts bias the agent to call graphify query "..." before falling back to raw file reads. The graph itself is exposed through an MCP server, a CLI, and a /graphify slash command for ad-hoc access. Installation produces persistent files — a graph.json, an interactive HTML audit view, and a GRAPH_REPORT.md — so the index can be queried weeks later without re-reading the codebase (tokenade.net, Medium).
Headroom occupies the stage immediately before the API call. It can be wired in three ways: a Python SDK call to headroom.compress(...), a CLI proxy that rewrites the conversation window before each request, or an MCP server. The documented lifecycle runs through eleven phases — Setup → Pre-Start → Post-Start → Input Received → Input Cached → Input Routed → Input Compressed → Input Remembered → Pre-Send → Post-Send → Response Received — implemented by three working components:
Compression is reversible: originals live in a local LRU cache, exposed through an injected headroom_retrieve tool with optional BM25 sub-search (tokenade.net).
Caveman does not hook into the pipeline at all. It is a skill — a ruleset — dropped into CLAUDE.md, AGENTS.md, or .cursor/rules/, where it in-band conditions generation through directives such as no filler, no preamble, no postamble, silent tool use, compress prose, and preserve technical artifacts (Medium). Because it lives in the markdown instructions the agent already reads, it requires no runtime hook and no additional process.
The three installation footprints differ fundamentally: Graphify writes persistent hook files and a generated graph, Headroom requires a runtime proxy or SDK call, and Caveman is just a markdown edit. This means the layering question is one of runtime coexistence — whether Headroom's pre-send rewrite interferes with Graphify's retrieval-time outputs, and whether Caveman's behavioral rules interact with either — rather than file-system overlap.
Headroom and Caveman operate on structurally different parts of the request lifecycle, so their savings stack additively rather than fight each other. Headroom is out-of-band infrastructure — typically a proxy or wrapper that intercepts the message array before it leaves the host and rewrites it into a more compact form on its way to the provider. Caveman is in-band prompt conditioning — a skill or rules file the agent reads at startup that changes the register in which the model emits tokens (app.thetestingacademy.com). Headroom dries out what comes in; Caveman dries out what comes out; the reasoning in the middle is untouched.
The only point where these two tools can collide is the provider's prompt prefix cache, and Headroom is engineered specifically to avoid being a problem there. Its CacheAligner stage runs before any compression happens and never rewrites the static prefix itself — instead it detects volatile content like rotating timestamps, session tokens, and UUIDs embedded in the system prompt and relocates them into the live zone so the stable prefix remains byte-identical across turns (github.com/headroomlabs-ai/headroom; alphamatch.ai). Live-zone compression only touches fresh bytes added on the current turn, so the frozen prefix keeps hitting the provider's KV cache and the per-call cost stays at the cached tier rather than re-paying full prefill (dev.to/arshtechpro). Even Headroom's own output-side verbosity steering appends its "be terse" instruction to the tail of the system prompt — not the head — precisely so the cached prefix is preserved.
Caveman works by giving the model a compact set of instructions to answer in tight caveman-speak: drop articles, filler, pleasantries, and hedging; keep technical terms, code, commits, and errors verbatim. Nothing intercepts or rewrites the model output after the fact — the model itself simply emits fewer tokens. Because the rules file does not modify the prompt at all, the cached prefix is untouched by definition (app.thetestingacademy.com). That is also why a single Caveman install rides any agent that reads a skill or rules file — Claude Code, Codex, Cursor, Copilot, and 30+ others — without needing per-provider integration.
Order of activation between Headroom and Caveman is not load-bearing, but the safest configuration is to enable Headroom's CacheAligner first, run a short multi-turn session to confirm prefix stability, and then add Caveman to the rules file. After that, verify in the provider's cache-hit metrics that turning on Caveman does not change the prefix byte-for-byte — it should not, but it is worth checking rather than assuming. With both in place, an agent typically sees input savings from Headroom on the order of 60–95% on context tokens (measured peaks of 93.9% on build logs and 92% on code-search workloads) layered on top of Caveman's roughly 65% reduction in output tokens, with the provider's cache-hit discounts preserved on both sides (pasqualepillitteri.it; caveman.so).
The three tools sit at structurally different points in the request lifecycle, and Graphify's point is the furthest upstream. Where Headroom and Caveman are context-shaping tools that operate on whatever reaches the model, Graphify prevents certain inputs from ever being created: if the agent never re-reads a file, there is no tool output for Headroom's ContentRouter to compress and no input prose for Caveman's output-voice rules to abbreviate on that read. This sidesteps the overlap problem rather than creating one, which is the main reason the three can be stacked without diminishing returns.
The mechanism is concrete. On hook-enabled platforms — Claude Code, Gemini CLI, and CodeBuddy — Graphify installs a PreToolUse hook that fires before any Read, Glob, or Bash search call runs, redirecting the agent to a graph query instead. On platforms without hook support, it writes a rule file (CLAUDE.md for Claude Code, AGENTS.md for Codex, .cursor/rules for Cursor, CODEBUDDY.md for CodeBuddy) instructing the assistant to prefer graphify query "..." over raw file reads. Either way, the read is replaced, not duplicated.
The graph itself is a one-time upfront cost amortized over subsequent queries. Graphify writes persistent, inspectable artifacts — graph.json for the queryable index, an HTML view for human audit, and a Markdown report — and uses a cache directory so only changed files are re-processed on subsequent builds. This matters for stacking: because the graph is built once and reused, the marginal cost of letting Headroom and Caveman operate on whatever still flows through the pipeline is unchanged, while the volume of redundant reads flowing into that pipeline has dropped.
That residual pipeline is still substantial enough to keep both downstream tools useful. Once Graphify is in place, Headroom still has plenty to compress — live transcripts, command output that bypasses Graphify, RAG payloads, logs, and agent-to-agent messages — and Caveman still has plenty to do at the output register. Neither tool is made redundant by Graphify; each one simply receives a cleaner, smaller feed.
The practical implication is a layering rule: Graphify is the foundation, and Headroom and Caveman stack on top of it. Composition at this level is clean because each tool's savings are counted in inputs the others never see.
Sources: Graphify vs Headroom comparison, Headroom vs Caveman on combined use, Tool stacking tier guidance.
Most of the trio stacks cleanly because each tool targets a different point in the request lifecycle, but one pairing still produces real overlap: Headroom's input compression and Caveman's /caveman-compress mode both fight over the same bytes before the model sees them. Because Headroom's SmartCrusher already claims 60–95% reduction on context — with measured peaks of 93.9% on build logs and 92% on JSON arrays of a hundred elements — there is little structural redundancy left for a second pass to recover. Once a noisy JSON payload has been collapsed by SmartCrusher or a build log has been pattern-clustered, /caveman-compress (documented at roughly 46% input reduction) has diminishing leftover to remove. What it does add is latency from a second compression stage and, worse, a second mutation of the prompt prefix that can interact badly with Headroom's CacheAligner, which is specifically designed to keep volatile content from busting the provider's KV cache.
A second, subtler overlap appears between Graphify and Headroom. Graphify's job is to replace ad-hoc file reads with structured graph queries, so its output (GRAPH_REPORT.md) is meant to be the compact surface the agent reasons over. If Headroom's Kompress-v2-base then runs prose compression over that summary, the second pass is mostly catching redundancies the graph query already abstracted away. The result is two compression layers spending tokens and time on a document that was already designed to be small.
Three rules keep the stack honest:
/caveman-compress should be disabled in this configuration.Follow those rules and the trio behaves more like three levers on three different quantities than three compressors racing for the same bytes.
Graphify goes in first because it is the longest-running component of the stack and the only one that writes persistent hooks. The official PyPI package is graphifyy (double-y) and requires Python 3.10 or newer. Install it with pip install graphifyy (or, for an isolated environment, uv tool install graphifyy / pipx install graphifyy), then run graphify install to register the skill with your AI assistant. From inside the assistant, run /graphify ./myproject to build the graph; three artifacts land in the output directory: graph.json (full graph), GRAPH_REPORT.md (curated highlights), and graph.html (interactive visualization). Before moving on, verify that CLAUDE.md received the Graphify section and that the PreToolUse hook is registered in the platform's settings — that hook is what makes the agent consult the graph before falling back to raw file reads.
Headroom is runtime infrastructure that should be validated before any output-conditioning ruleset takes effect, so it goes in second. Wire it in either as the CLI proxy in front of the model or by importing the SDK into the agent loop. With a session open, check two things: that CacheAligner reports a stable hash for the system prompt across consecutive turns (meaning volatile content such as timestamps, session tokens, and UUIDs is being moved to the tail of the prompt rather than embedded mid-prefix), and that live-zone compression is engaging on fresh tool output. The key invariant Headroom guarantees is that the frozen prefix of each request stays byte-identical so the provider's KV cache is not busted — confirmation comes from observing compression only on bytes that arrived this turn.
Only after Graphify and Headroom are verified should Caveman's ruleset be appended to CLAUDE.md, because Caveman sits at the model-output stage and is the layer where prefix-stability regressions would be cheapest to introduce. Start with Full mode, which benchmarks at roughly a 65% mean reduction in output tokens across tiktoken-verified tasks while leaving code, commands, and errors unchanged. After enabling it, re-check the provider cache hit rate to confirm that the prefix bytes are still byte-identical; if they are not, Caveman is being injected in front of the system prompt rather than at the end.
Track input tokens per turn with Codex CLI's token counter or LangSmith, split graph-read tokens from raw-file-read tokens, and confirm across a representative session that Graphify's share of input is non-zero (proof the agent is consulting the graph) while Headroom's share of compressed bytes is also non-zero (proof live-zone compression is firing).
Each tool in the stack quotes a different shape of win, and none of them should be carried into planning unchanged.
A meaningful caveat: per-payload compression rates do not always translate into session-level savings. On one independent long-session benchmark, neither Headroom nor Graphify produced a measurable cost win — Headroom finished 53% more expensive than running no tool at all (Tokenade). Mechanism, not headline percentage, is what to evaluate.
Because the three tools target structurally distinct waste — output voice, inbound tool/context payloads, and repeated file reads — their savings are at best additive, not multiplicative. On a typical mixed workload, expect additive-to-sub-additive savings on the order of 40–60%, with larger gains on exploration-heavy sessions and smaller gains on already-tight ones. Multipliers only hold where each tool's specific waste exists in quantity.
Budget for compounding savings only on workloads that exhibit the underlying waste:
In tight, single-file, single-turn workflows the headline numbers will not materialize, and the cost of running the stack can erase the savings entirely.