Headroom vs Aphrodite: The Context Compression War - Your LLM is Burning 90% of Tokens on Junk

$80 per Bookmark

In April, I was debugging a trace why the service menu was returning 500. Claude Code ran, sent the stack trace in, loaded the service file, then sent the gateway file, and also sent the DB schema. 3 seconds later - bing - it responded. After reading it, I just sat there in silence.

Each time I called Claude Code, it re-read the entire output from the previous command. A 150-line build log? Read. A 42-line git diff? Read. A browser snapshot with 342 elements? Also read. Who knows what percentage of that was output it wrote itself, returned, and then re-read in the next call.

It turns out I’m not the only one. The output from the tool that LLM returns after each call - git diff, build log, terminal output, JSON blob - all of it gets stuffed into the context for the next inference. And LLM re-reads the entire thing, including what it output just 5 seconds ago. 90% of the tokens in your context window are being used to store things the model never needs to re-read again 💀

So I started looking for a solution.

The Problem: Why is the Context Full of Junk?

Every time an LLM agent (Claude Code, Hermes Agent, Cursor, Aider…) runs a tool call, it receives output - which can be the result of git diff, cat file, curl API, or pytest. This output is appended to the message history. In the next call, the entire history - including this output - is sent back to the model.

This loop occurs dozens, hundreds of times in a single working session. And the model has to “read” the entire history every time.

What are the consequences?

• Wasted tokens. Model returns output → output becomes input → tokens are wasted in both directions, costing $.
• Context window fills up quickly. 200K tokens can fill up after 5-10 tool calls if the output is large.
• Compression must run sooner. Context compression built-in to Hermes Agent, Claude Code runs, but it is lossy - summarizing, losing original data. When the agent needs to look up old details, they are no longer there.
• Agent " forgets" quickly. Because the context is full of junk, the truly important information is pushed out of the window.

This is exactly the problem that output context compression was born to solve. Instead of stuffing the entire tool output into the context, compress it into a small preview - and keep the original in another place. When needed, the agent can retrieve it via a hash.

This approach is called CCR - Content Classification & Retrieval. And both Headroom and Aphrodite are built on this foundation.

CCR: The Output Compression Machine

CCR is not a lossless compression like gzip. It is smarter - classifying content, generating previews, and allowing for accurate retrieval when needed.

The basic process:

1. Classify - Agent output is classified: git diff, build log, traceback, terminal output, JSON blob, HTML snapshot, table, etc. Headroom uses a 28-type regex classifier, and Aphrodite uses a similar classifier.
2. Preview - A compact preview is created. For example, a 42-line git diff becomes [git_diff:files=3,+28/-14]. A 1400-token build output becomes [build:status=fail,error=undefined_service].
3. Store - The original content is hashed (BLAKE3) and stored in SQLite or an in-memory store.
4. Serve - The agent reads the preview, and if the full content is needed, it calls for retrieval by hash.

Both Headroom and Aphrodite implement CCR, but each has its own style - differing from the implementation language, deployment method, to target users.

Headroom (55.2K ⭐) - The Python Beast

Headroom, developed by headroomlabs-ai, version 0.28.0, is composed of 80% Python and 15% Rust. With 1,815 commits and over 160 contributors, it operates under the MIT license. The number of GitHub stars speaks for itself - 55.2K is a staggering figure for an infrastructure tool.

Architecture

Headroom is not just a library; it’s a comprehensive system:

• Python library - Install with pip install headroom-ai and use immediately. Import into your script, wrap your function, and automatically compress output.
• HTTP proxy - Runs as a forwarding proxy, compressing output before sending it to the LLM API. Transparent to the agent.
• MCP server - Model Context Protocol server, integrating with any MCP client.
• Claude Code plugin - Native .claude-plugin/, running headroom wrap claude sets it up automatically.
• headroom wrap cursor/aider - Wrapper CLI for IDE agent tools.

Compression Layers

Headroom features three compression layers:

ModernBERT ONNX - An ML model (based on BERT) running through the ONNX runtime. This layer learns output patterns and creates intelligent previews, handling content that rule-based methods cannot. Fast, with a model size of approximately 15MB.

TextCrusher (Rust native) - The Rust component, compiled into a native binary. Regex-based, zero-dependency, and sub-millisecond for all content types. Suitable for simple cases like git diff, terminal output, and log lines.

SmartCrusher - Combines both layers above: it first attempts to use TextCrusher (fast, sub-ms). If a pattern does not match (e.g., unusual content or non-standard format), it falls back to ModernBERT. Offers the best of both worlds.

Token Savings

Headroom claims 60-95% token savings, depending on the content type. A Netflix engineer used it and saved $111M in 5 months. Yes, $111M. One hundred eleven million dollars. From an open-source tool. 💀

Setup: pip install headroom-ai - completed in 30 seconds. headroom wrap claude takes an additional 10 seconds.

Strengths

• Huge community. 160 contributors, with issues and PRs resolved within hours.
• Multi-mode. Can be used in various forms - library, proxy, MCP, CLI wrapper.
• Mature. Version 0.28.0 with continuous bug fixes and comprehensive documentation.
• Claude Code first-class support. Native plugin, set up with a single command.

Weaknesses

• Python dependency. If your stack does not include Python, installing Python and pip just for this tool can be cumbersome.
• Performance overhead. ModernBERT ONNX is fast but still introduces latency, especially on machines without a GPU.
• Non-native Hermes Agent support. The plugin is not a native dylib but runs through the MCP server or proxy.
• Complex configuration. Too many options can be overwhelming for new users.

Aphrodite (16 ⭐) - The Rust Challenger

Aphrodite, developed by PlayForm (Nikola Hristov), version 1.0.6, with 73% Rust code, is licensed under CC0-1.0. With only 16 GitHub stars, it may seem insignificant compared to Headroom, but don’t let the number of stars deceive you.

Its tagline is: “Your LLM burns 90% of its context on output it never reads.” - a painful truth.

Architecture

Aphrodite is a fork of Headroom, but rewritten almost entirely in Rust. It embeds Headroom as a vendor submodule, taking ideas and CCR design from Headroom, but implementing them in a more optimized way for a specific niche.

• Native Hermes Agent plugin. This is the biggest difference. libaphrodite_hermes.{dylib,so,dll} - loads directly into the Hermes Agent process, with zero network hops. 12 tools (aphrodite_*), 5 hooks, and a context engine.
• Dual proxy. Ports :9797 (cache proxy) and :9798 (token/SQLite proxy). :9797 is a transparent cache, while :9798 is an SQLite-based token counting and storage.
• 28-type regex classifier. Similar to Headroom’s TextCrusher, implemented in Rust.
• CCR engine. BLAKE3 hashing → SQLite storage → marker-based retrieval.
• Content-type routing. Rust match pattern, compile-time optimization, and zero runtime overhead.

Speed

Aphrodite claims sub-millisecond compression, with a 12,800× maximum compression ratio. This means 1MB of output can be compressed to approximately 80 bytes. It sounds crazy, but with a snapshot of 5000 HTML tokens → [browser:342el] 12 tokens, the ratio is indeed that high.

Token Savings (Real-World Benchmark)

The 416× ratio for browser snapshots is insane. 5,000 tokens → 12 tokens. Without compression, those 5,000 tokens would be read again on each round trip. With 10 round trips, that’s 50,000 tokens wasted 🔥

Strengths

• Native support for Hermes Agent. No proxy or MCP needed, loads directly into the process. 12 tools + 5 hooks = comprehensive control.
• Speed. Rust compile-time optimization, sub-millisecond compression.
• CC0 license. Public domain - no restrictions. Copy, modify, and commercial use are all allowed.
• Lightweight. No Python, ONNX, or model files needed. Compact binary, runs on any OS.
• Double proxy for production. Separate cache and token counting.

Weaknesses

• Requires building from source. No prebuilt binary. Git clone + submodule update + cargo build takes 5-10 minutes. If you don’t have the Rust toolchain, add 10-15 minutes for installation.
• Only targets Hermes Agent. Want to use it with Claude Code, Cursor, or Aider? No native support. Must use dual proxy mode (:9797 + :9798) - a workaround, not seamless.
• Tiny community. 2 contributors, 16 stars. Bugs may persist, and few people test edge cases.
• Sparse documentation. Compared to Headroom, Aphrodite’s docs are basic, only covering the README. To understand it deeply, you need to read the source code.
• Dependence on Hermes Agent plugin system. Hermes is rapidly developing, and the plugin API may change.

Benchmark: Token Savings

I don’t have a physical machine to run benchmarks for both (haven’t installed any tools - this article is research-based). However, here are the statistics compiled from the community for the same content type:

Bottom line: Aphrodite is 10-30% better in terms of compression ratio for most content types. Why? Rust compile-time optimization + optimized regex pattern matching compared to Headroom’s Python-based classifier. However, at a small scale (less than 100K tokens/day), this difference is almost negligible.

Usecase 1: Claude Code

If you use Claude Code, Headroom is the clear choice:

• pip install headroom-ai + headroom wrap claude = 40-second setup.
• Native .claude-plugin/ support - Claude Code auto-detects.
• Large community, bugs are fixed quickly.
• Many Claude Code users have used and reported results.

Where is Aphrodite? To use it with Claude Code, you need to set up a dual proxy (:9797 cache + :9798 token). It works, but it’s not the “it just runs” experience like Headroom.

Winner: Headroom - 1-line setup, native plugin, large community.

Usecase 2: Hermes Agent

This is Aphrodite’s home ground.

• Native dylib plugin - loaded directly into the Hermes process, no network hop, no MCP, no proxy config.
• 12 tools - aphrodite_compress, aphrodite_retrieve, aphrodite_classify, aphrodite_stats… Full control.
• 5 hooks - pre-compress, post-compress, pre-retrieve, post-retrieve, on-error.
• Context engine plugin - Replaces Hermes’ built-in context compressor with CCR.

Setup:

git clone https://github.com/PlayForm/aphrodite
cd aphrodite
git submodule update --init --recursive
cargo build --release
ln -sf $(pwd)/target/release/libaphrodite_hermes.so ~/.hermes/plugins/aphrodite/aphrodite.so
hermes plugins enable aphrodite

Done. Hermes automatically loads the plugin, tools appear, and context compression runs natively.

Headroom can be used with Hermes Agent via an MCP server or HTTP proxy. But that’s an add-on, not native integration. Adds another network layer, another failure point, and more config to manage.

Winner: Aphrodite - native, zero-overhead, 12 tools, 5 hooks.

Usecase 3: Gateway LLM proxy

If you run an LLM gateway (e.g., using Hermes Gateway, OpenRouter, or a custom proxy) for multiple agents to share:

Headroom:

• headroom proxy --port 8080 - runs proxy mode immediately.
• HTTP proxy, transparent to all clients.
• No need to configure each agent.
• Has MCP server mode if needed.

Aphrodite:

• Dual proxy: :9797 (cache) + :9798 (token/SQLite).
• Cache proxy automatically caches compressed output, reducing redundant compute.
• Token proxy tracks real-time token usage, persisting into SQLite.

With production scale, Aphrodite’s dual proxy has an advantage: one port for cache, one port for observability. But if you only need to quickly run a proxy for a small team, Headroom is much simpler.

Winner: Tie - Headroom if you need a quick setup, Aphrodite if you need a production-grade dual proxy + persistence.

Setup guide: Install both in 30 minutes

Headroom (30 seconds)

pip install headroom-ai

# With Claude Code
headroom wrap claude

# With Cursor
headroom wrap cursor

# With Aider
headroom wrap aider

# Or run proxy
headroom proxy --port 8080

Easy, no need to think. Python ecosystem, pip install is done.

Aphrodite (10 minutes)

# 1. Git clone + submodule
git clone https://github.com/PlayForm/aphrodite
cd aphrodite
git submodule update --init --recursive

# 2. Build (requires Rust toolchain)
cargo build --release

# 3. Setup Hermes plugin
mkdir -p ~/.hermes/plugins/aphrodite
ln -sf $(pwd)/target/release/libaphrodite_hermes.so \
  ~/.hermes/plugins/aphrodite/aphrodite.so

# 4. Enable
hermes plugins enable aphrodite

# 5. Or run dual proxy
./target/release/aphrodite-proxy --cache-port 9797 --token-port 9798

Takes more time but installs once and for all. If you already have the Rust toolchain, the build part only takes 2-3 minutes.

System requirements

When to Choose What?

Choose Headroom if:

• You primarily use Claude Code - native plugin, one-line setup.
• You want a multi-mode solution: library, proxy, MCP, CLI wrapper.
• Your team is familiar with the Python ecosystem. Install with pip install and run immediately.
• You need a large community - issues resolved within hours, comprehensive documentation.
• You want zero friction when setting up. Finished in 30 seconds.

Choose Aphrodite if:

• You use Hermes Agent - native plugin, 12 tools, 5 hooks, zero overhead.
• You want maximum speed - Rust, sub-millisecond compression.
• You need production dual proxy - separate cache port and token port.
• You prefer the CC0 license - public domain, no legal concerns.
• You don’t mind building from source - Rust compile-time optimization is worth the effort.

If you use both…?

You can run both Headroom and Aphrodite on the same machine. Headroom works with Claude Code, while Aphrodite works with Hermes Agent. They do not conflict. However, to be honest - just choose the one that fits your primary tool chain.

Personal Verdict

I haven’t installed any tools - this article is purely research-based. But based on what I’ve read, I think this:

Headroom is the safe choice. 55K stars, large community, multi-mode, 30s setup. If you only have 15 minutes to try one, Headroom is the one to try. It’s likely to work well and you won’t need to look back.

Aphrodite is the “right if it fits” choice. Native Hermes plugin is a killer feature - but only if you use Hermes Agent. 16 stars is a risk: few people test, bugs may exist for a long time, documentation is thin. But if you’re a Hermes user, the native plugin experience is worth 10 times the proxy configuration.

As for the story of 90% of tokens being wasted - it’s not drama, it’s the truth. Each time Claude Code or Hermes Agent runs a tool call, the entire output is appended to the context. The next call, the model reads it all again. Tool output occupies 70-90% of the context window in long sessions - most of which is information the model doesn’t need to read again.

Compressing output context is no longer a “nice to have”. It’s essential infrastructure for anyone who uses AI agents frequently. 50K tokens saved per round trip with 20 round trips per day = 1M tokens/day. With Claude Sonnet 4 ($3/M tokens input), that’s ~$90/month in savings. Just for you. With an open-source tool.

Now it’s your turn.

Try installing Headroom: pip install headroom-ai - 30 seconds. Or build Aphrodite for Hermes Agent: clone the repo on GitHub - 10 minutes.

Then come back here and comment on which one you choose and how many tokens you save. I’m curious 🤡

• Headroom GitHub →
• Aphrodite GitHub →
• Hermes Agent Docs →