Headroom Context Compression plugin thumbnail

Headroom Context Compression

Automatically compresses tool outputs in your agent conversations using Headroom AI. Saves 50-70% tokens on every agent turn by compressing file reads, command output, search results, and API responses. Works with any LLM provider. Zero configuration needed — install, run setup, done.

Author emasoudy 1 stars Version 1.0.0 Updated
LlmPromptingOptimization
GitHub Repository Discussion How to install

README

Headroom Compress

Automatically compresses tool outputs in your Agent Zero conversations — saving 50-70% tokens on every agent turn.

What It Does

Every time your agent reads a file, runs terminal commands, searches code, or fetches API responses, that output gets stored in the conversation context. Over a long session, these tool outputs pile up — consuming thousands of tokens on every subsequent LLM call.

Headroom Compress runs automatically before each LLM call. It finds tool outputs in your conversation history and compresses them using Headroom AI — typically reducing them by 50-70% while preserving the essential information.

The result: your agent stays sharp in long sessions, your context window lasts longer, and you spend less on API costs.

How It Works (for users)

  1. Agent reads a large file or runs a command → output lands in conversation history
  2. Before the next LLM call, the plugin scans the conversation for old tool outputs
  3. Each large tool output is compressed in place — keeping structure, trimming redundancy
  4. The LLM receives a lighter context, responds faster, and costs less
  5. A stats dashboard shows you exactly how many tokens you've saved

Key Features

  • Automatic — No manual steps. Install once, compression runs on every agent turn.
  • Safe — Only compresses tool outputs (file reads, command results, search output). Never touches your system prompts, instructions, or behavioral rules.
  • Transparent — If compression fails for any reason, the original content is used unchanged. Your agent never breaks.
  • Surgical — Decomposes tool result JSON, compresses only the output data, and puts it back without touching the rest of the message.
  • Persistent Stats — Tracks total tokens saved across sessions. View them in the plugin settings dashboard.

Installation

From Plugin Hub

  1. Open Plugins in your Agent Zero UI
  2. Search for Headroom Compress
  3. Click Install
  4. Click Run Setup (installs the headroom-ai Python package automatically)
  5. Done — compression starts on your next agent conversation

Manual

# From your A0 plugins directory
cd /a0/usr/plugins/
git clone https://github.com/emasoudy/headroom-compress-a0.git headroom_compress

# Install the dependency
pip install headroom-ai

Restart Agent Zero after manual installation.

Settings

Setting Default What It Does
Min field tokens 200 Tool outputs smaller than this are skipped. Lower = more compression.
Target compression ratio 0.5 How aggressively to compress (0.1 = light, 0.9 = aggressive).
Log compression stats true Shows compression events in the agent log panel.

Stats Dashboard

The plugin settings page includes a live dashboard:

  • Tokens Saved — cumulative tokens saved across all sessions
  • Avg Compression — average compression rate across all events
  • Fields Compressed — total tool outputs compressed
  • Compression Events — total LLM calls where compression fired
  • Recent Activity — last 8 compression events with tool name, before/after tokens, and timestamp

Requirements

  • Agent Zero (any recent version)
  • headroom-ai Python package (auto-installed by the Setup button)

Compatibility

Works with any LLM provider — OpenAI, Anthropic, Google, local models, or any provider configured in Agent Zero. Token savings are the same regardless of provider.

Uninstall

  1. Open Plugins in your Agent Zero UI
  2. Find Headroom Compress
  3. Click Uninstall

The headroom-ai package is intentionally not removed (other plugins may depend on it). To remove it manually:

pip uninstall headroom-ai

License

MIT

Author

Essam Masoudy — emasoudy.com