Development Tools

Headroom Setup Guide: Compress AI Agent Context and Token Use

Set up Headroom to compress AI agent context, logs, tool output, and RAG snippets for Claude Code, Codex, Cursor, and MCP while reducing token use.

chopratejas/headroom is a tool for context compression for AI Agents. The problem it solves is very realistic: while the agent is running commands, reading logs, searching for code, and stuffing RAG fragments, the context window will soon be filled, and the cost and delay will rise together.

The idea behind Headroom is to compress tool output, logs, files, RAG clips and session history before the content enters LLM. The goal written in the README is very straightforward: reduce 60-95% tokens while trying to maintain the quality of answers.

Quick Answer

Headroom is a local context-compression layer for AI agents. It can wrap Claude Code, Codex, Cursor, and MCP workflows, shrink noisy logs and tool output before they reach the model, and retain the original content for later retrieval. Test compression quality on your own tasks before relying on the project’s token-saving claims.

What problem does it solve?

Many agent tools now do not have models that are not smart enough, but the context is too dirty:

  • grep, rg, log query returns hundreds or thousands of rows at a time;
  • RAG search fragments are repeated, redundant, and formatted;
  • There are a large number of low-value fields in JSON, stack trace, and SQL results;
  • After multiple rounds of debugging, the old output occupies the context;
  • Tools such as Claude Code, Codex, Cursor, and Aider each maintain context, making it difficult to share memory.

Headroom is the “cleaner before entering the model”. It does not replace LLM, nor does it replace RAG, but adds a layer of compression, routing, caching, and traceable retrieval in front of LLM.

Core Competencies

From the README, Headroom has several main usage forms:

  • Library: directly call compress(messages) in Python or TypeScript;
  • Proxy: Use headroom proxy --port 8787 as OpenAI-compatible proxy;
  • Agent wrap: Use headroom wrap claude|codex|cursor|aider|copilot to wrap an existing Agent;
  • MCP Server: Provides headroom_compress, headroom_retrieve, headroom_stats for use by MCP clients;
  • Cross-agent memory: Let Claude, Codex, Gemini and other tools share local memory and automatically remove duplicates;
  • headroom learn: dig experience from failed sessions, write CLAUDE.md or AGENTS.md;
  • Reversible compression: The original text will not be deleted and can be retrieved through the search tool if needed.

These forms are crucial. It is not an SDK that can only be embedded in the code, nor can it only be used as a proxy. You can start with the lightest wrap mode and decide whether to integrate it into your own application.

How does it compress?

There are several keywords in the structure of Headroom:

  • ContentRouter: identify the content type and select the corresponding compressor;
  • SmartCrusher: prefers to process structured content such as JSON;
  • CodeCompressor: prefers processing code and AST;
  • Kompress-base: used for text compression;
  • CacheAligner: Make the prompt prefix more stable and improve the provider’s KV cache hit rate;
  • CCR: Save the original text and retrieve it through retrieve when needed.

In human terms, it does not roughly summarize all the content into a paragraph, but first determines the content type and then selects different compression strategies. Code, JSON, plain text, logs and RAG fragments should not be compressed in the same way.

Quick installation

The installation method given in the README is very straightforward:

1
2

pip install "headroom-ai[all]"
npm install headroom-ai

The Python side requires Python 3.10+. After installation, you can try these commands first:

1
2
3

headroom wrap claude
headroom proxy --port 8787
headroom perf

If you are using the MCP client, you can go:

1

headroom mcp install

If you just want to verify the effect, the easiest thing is to run headroom perf first to see how many tokens it can save for typical workloads. After confirming that it is available, connect it to Claude Code, Codex, Cursor or your own OpenAI-compatible client.

What is the difference between ## and ordinary summary?

The biggest problem with ordinary abstracts is that they are irreversible. The log is summarized as “Database connection failed”, and you can’t see the original error code, timestamp, call stack and context. If the Agent needs details later, he can only check again.

One of the key points of Headroom is reversible: the original content is saved locally, compressed and passed to the model; if the model requires the original text, it is retrieved through headroom_retrieve. This design is more suitable for debugging, code search, and production log analysis, because these scenarios often require going back to details.

Of course, this also means you have to manage local storage and privacy boundaries. Although the README emphasizes local-first, as long as you send the compressed content to the cloud model, you still have to handle it according to your own data security requirements.

Which scenarios are suitable?

I think Headroom is best suited for these scenarios:

  • Claude Code, Codex, and Cursor often slow down because the tool output is too long;
  • Use Agent to analyze large warehouses, search results and file fragments can easily explode the context;
  • When troubleshooting, SRE should show logs, traces, configurations and command output to the model;
  • When doing RAG applications, the search results are seriously redundant;
  • Want to share local memory between multiple Agent tools;
  • Want to integrate MCP tools into existing AI workflows.

If you only ask for a few chats occasionally, or the prompt is very short, you don’t necessarily need it. The value of Headroom mainly appears when “Agent is really doing work”.

What should you pay attention to when using it?

Contextual compression is not magic. It can save tokens, but it may also bring new problems:

  • When the compression strategy is inappropriate, the model may not be able to obtain key details;
  • Code and log scenarios need to test whether retrieve is reliable;
  • When accepting the proxy mode, confirm which local and cloud links the request passes through;
  • When used by teams, local caching, session recording and sensitive data retention policies must be defined;
  • Don’t just look at token savings, but also look at task completion rate and misjudgment rate.

My suggestion is to test with real tasks instead of just watching demos. For example, take a set of historical bugs, CI logs, RAG queries and code search tasks, and compare the cost, speed and answer quality of “feeding the model directly” and “passing through Headroom” respectively.

Native Claude Code token and cache optimization

Prompt Cache does not cache plain text

Prompt Cache is not just a string cache for prompts. In Transformer inference, what matters is the Key/Value state calculated by attention layers from the prefix context, usually called KV cache.

That means two things:

  • If the prefix stays stable, part of the previous computation can be reused.
  • If the model, tool definitions, system prompt, or prefix messages change, old cache entries may no longer match.

Anthropic’s documentation summarizes the invalidation hierarchy as tools -> system -> messages. Changes to tool definitions can invalidate the whole cache; system changes affect system and messages; message changes mainly affect message cache.

Claude Code adds more context sources such as CLAUDE.md, Skills, MCP, plugins, and subagents, so it is easier to accidentally break cache reuse.

Cache killer 1: switching models mid-task

Switching models is one of the most expensive changes.

Prompt Cache is isolated by model. Opus, Sonnet, and Haiku have different architectures and weights, so the KV cache calculated from the same text is not interchangeable. If you build a long context in Opus and then switch to Sonnet, Sonnet cannot reuse Opus’s cache.

This creates a counterintuitive result: switching models mid-task to save money may make the previous cache useless. Context that could have been read at cache-read price may need to be written and computed again.

A steadier pattern is:

  • Keep the main conversation on one model.
  • Use a subagent for side tasks that can run on a cheaper model.
  • Let the side agent search, explore, or summarize, then hand a concise result back to the main conversation.

This keeps the long main-context prefix stable and improves cache hit consistency.

Cache killer 2: adding MCP or reloading plugins mid-task

MCP provides tools to Claude Code. When you add an MCP server, the tool list changes, and tool definitions sit at the far left of the context chain.

From a Prompt Cache perspective, when the tool list changes, the system and messages that follow may need to be recalculated. If you use many MCP servers, the tool definitions themselves can be large, so the cost of invalidation becomes obvious.

One detail matters: Claude Code usually reads MCP configuration at session startup. Changing config mid-session may not affect the current session immediately. The dangerous moments are restart, resume, plugin reload, or anything that rebuilds the tool list.

Recommended practice:

  • Install required MCP servers before starting a long task.
  • Avoid discovering missing tools halfway through and then reloading.
  • Reduce default-enabled MCP servers when possible.
  • Do not keep rarely used MCP servers always enabled.

Stable tool definitions are the foundation of stable Prompt Cache hits.

Cache killer 3: editing CLAUDE.md mid-session

CLAUDE.md is Claude Code’s project memory file. It is useful for build commands, test commands, architecture conventions, code style, and project-specific constraints.

It is helpful, but it also enters the context. Claude’s help documentation explains that CLAUDE.md is read at session start and delivered as a user message. It also benefits from Anthropic Prompt Cache: the first request pays full input price, while later requests can hit the lower cache-read price if the cache is still valid.

The catch is that CLAUDE.md is content-addressed. Once the file changes, the old cache no longer matches.

So avoid frequently editing CLAUDE.md during a long task. Better practices:

  • Check whether CLAUDE.md is sufficient before the task starts.
  • Put stable rules in the file and temporary instructions in the current conversation.
  • Do not edit long-term memory for one-off instructions.
  • If you must change it, treat the next stage as a new session or new phase.

CLAUDE.md should be stable project guidance, not a scratchpad that changes every round.

Cache killer 4: installing or updating Skills mid-task

Skills are also part of the context. Installing a new Skill, updating a Skill, or changing the Skill list changes what gets injected into the session.

These changes often do not fully take effect until reload, resume, or a new session. Once messages are rebuilt, old cache entries may no longer match.

The same advice applies:

  • Decide which Skills are needed before starting.
  • Keep the Skill set stable for the same kind of task.
  • Avoid installing Skills in the middle of a long task.
  • If you install a new Skill, treat it as the beginning of a new stage.

For repeatable workflows such as content production, review, deployment, and translation, keeping a fixed Skill set helps keep the context structure stable.

Cache killer 5: idle time exceeding TTL

Prompt Cache does not last forever. A common default TTL is on the order of minutes, and Claude Code-related documentation often refers to roughly a five-minute cache window. After TTL expires, even the same request may need to rebuild the cache.

This explains a common feeling in long tasks: everything was cheap and fast, then after a coffee break the token cost jumps again.

Long tasks hit this easily. You may review Claude Code output, inspect files, run tests, or think about the next step. Five minutes can disappear quickly.

If your environment supports it, you can request a one-hour Prompt Cache TTL before long tasks:

1

export ENABLE_PROMPT_CACHING_1H=1

In Windows PowerShell:

1

$env:ENABLE_PROMPT_CACHING_1H="1"

One-hour cache writes usually cost more than five-minute cache writes. It is not always worth it for short tasks, but for large codebases, long conversations, and complex multi-step development, it may be cheaper than repeated cache expiration.

A token-saving Claude Code workflow

A steadier long-task setup looks like this:

  1. Choose the model before the task starts and avoid frequent switching.
  2. Enable the MCP servers you need and disable the ones you do not.
  3. Keep CLAUDE.md short, stable, and focused on durable rules.
  4. Prepare the Skills needed for this task in advance.
  5. For complex tasks, consider one-hour TTL.
  6. Split the task into phases, but keep context structure stable within each phase.
  7. Use subagents or separate sessions for side exploration instead of disturbing the main conversation.

The goal is not to prevent every cache miss. It is to avoid the high-cost misses that are easy to overlook.

A simple rule of thumb

Ask one question:

Does this operation change the model, tool definitions, system context, or fixed messages near the start of the session?

If yes, it probably affects Prompt Cache. The farther left it is in the context chain, the greater the impact.

Common operations:

  • Switch model: high risk, model caches are isolated.
  • Add MCP or reload plugins: high risk, tool list changes.
  • Edit CLAUDE.md: medium-high risk, project memory changes.
  • Install Skills: medium-high risk, injected context changes.
  • Continue normal conversation: low risk, mostly appends messages.
  • Idle past TTL: high risk, server-side cache expires.

Summary

Prompt Cache optimization in Claude Code is about keeping the session prefix stable.

Do not switch models casually. Do not install MCP servers and Skills halfway through. Do not use CLAUDE.md as a temporary scratchpad. For complex tasks, consider a longer TTL. Once these basics are stable, token cost and response speed become much more predictable.

The most practical sentence is: configure before you start, change less after you start.

Summary

Headroom is a typical “contextual engineering” tool. It does not seek to recreate an Agent, but stands between the Agent and the LLM, cleaning and shortening the content that enters the model, while retaining the ability to retrieve the original text.

It’s suitable for people who are already using Claude Code, Codex, Cursor, Aider, Copilot CLI or MCP tools. If your pain point is “the model context is often overwhelmed by logs and tool output”, Headroom is worth trying; if your problem is just insufficient model capabilities, simply compressing the context may not necessarily solve it.

Reference sources

FAQ

What is this project?

It is an AI tooling project covered in this article, with a focus on what it does, how to use it, and when it is worth trying.

Who is it for?

It is mainly for developers and AI tool users who want a practical way to connect the project to real workflows rather than only read the README.

What should I check before using it?

Check installation method, supported tools, data and permission boundaries, and whether the project is still changing quickly.

Is it suitable for production use?

Treat it as a tool to test carefully first. Verify behavior on a small workflow before applying it to sensitive or production tasks.