The biggest cost problem for AI agents is tokens.

Output tokens in particular can be 5× more expensive than input on some models (Opus-class). Every time an agent reads a long log and responds verbosely, costs scale exponentially.

Headroom solves this problem in two ways.

1. Context compression: Compress tool outputs, logs, and RAG chunks before they reach the LLM. 2. Verbosity steering: Guide agent responses to be concise, reducing output tokens.

Both are proxy-based, requiring zero code changes.

Context Compression: 60-95% Input Token Reduction

Headroom's core feature compresses tool outputs and logs.

Traditional agent flow:

  Tool execution → Full output (10,000 tokens)
                  ↓
  Inserted directly into LLM context
                  ↓
  "Find errors in this log" → Token waste

Headroom flow:

  Tool execution → Full output (10,000 tokens)
                  ↓
  Headroom compression (2,000 tokens, 80% reduction)
                  ↓
  Inserted into LLM context
                  ↓
  "Find errors in this log" → Compressed content is sufficient

Compression combines lossless structuring and meaning-preserving compression.

Compression effectiveness by target:
├── JSON arrays/logs: 90% (repeated patterns removed)
├── Code search results: 21-30% reduction
├── RAG chunks: 40-60% (duplicates removed)
└── Natural language output: 10-20% (already dense)

Compression cost is very low. p50 compression time for 10,000-token JSON is 0.21ms, and even at 100,000 tokens it's only 1.4ms. Agent latency is barely affected.

Verbosity Steering: 50% Output Token Reduction

If input tokens are a problem, output tokens are worse. On Opus-class models, output tokens cost 5× the input.

Common waste patterns when agents respond:

Typical response:
  "Great! Let me analyze this for you. 
   First, I'll look at the code structure...
   
   [code block — already in context]
   
   Here's what I found:
   - Line 42 has a null pointer issue
   - Line 87 needs error handling
   
   Let me know if you need more details!"

What Headroom removes:
  ❌ "Great! Let me analyze..." (preamble)
  ❌ "[Code block reprinted]" (duplicate)
  ❌ "Let me know if you need..." (postamble)

What remains:
  ✅ "- Line 42 has a null pointer issue"
  ✅ "- Line 87 needs error handling"

Headroom's headroom learn --verbosity command reads past sessions to automatically determine the user's preferred terseness level.

# Analyze past 10 sessions → determine preference
headroom learn --verbosity

# Result: "User prefers direct answers with code references. 
#          No greetings, no summaries."

Architecture: Proxy-Based — Zero Code Changes

Headroom's biggest advantage is its proxy architecture.

Traditional integration (code changes needed):

  Agent code ──▶ LLM API call
                ↓ (manual modification)
          [Insert compression logic]

Headroom proxy (no code changes):

  Agent code ──▶ Headroom Proxy ──▶ LLM API
                              ↑
                        Transparent compression/transform

The headroom wrap command sets up a proxy for specific agents, routing all API calls through Headroom for automatic compression.

# Set up Headroom proxy for Claude Code
headroom wrap claude-code

# Set up for Copilot CLI
headroom wrap copilot-cli

Supports 20+ agents: Claude Code, Codex, Grok CLI, Cursor, Aider, Copilot CLI, VS Code Copilot, OpenClaw, OpenCode, Cline, Continue, Goose, OpenHands, and more.

Benchmarks: Compression Impact on Accuracy

Headroom's official benchmarks show that compression has minimal impact on accuracy.

Compression ratio vs accuracy:

  SQuAD v2:     19% compression → 97% accuracy (same as baseline)
  BFCL:         32% compression → 97% accuracy (same as baseline)
  TruthfulQA:   ±0.03 (within statistical error margin)
  GSM8K:        ±0.000 (no change)

Conclusion: No detectable accuracy degradation at 20-30% compression

Token reduction in real agent tasks:

Tool search (100 results):  17,199 → 13,597 tokens (21% reduction)
SRE incident debugging:     55,957 → 24,340 tokens (57% reduction)
Codebase exploration:       58,801 → 33,895 tokens (42% reduction)
GitHub issue triage:        46,07 → 32,429 tokens (30% reduction)

The 57% reduction in SRE incident debugging reflects how compressed logs contain many repeated timestamps and structures.

Supported APIs

Headroom supports all major LLM APIs:

Anthropic:    /v1/messages
OpenAI:       /v1/chat/completions, /v1/responses
Gemini:       chat/completions

Since the proxy intercepts standard API endpoints, new models can be supported quickly as they emerge.

Limitations and Considerations

  1. Compression ratio variance: JSON and logs compress up to 90%, but natural language text only 10-20%. Already-dense output has limited compression benefit.
  2. Proxy setup: headroom wrap modifies environment variables or proxy settings. Conflicts may occur when running multiple agents simultaneously.
  3. Verbosity learning: headroom learn requires past sessions. New agents won't see immediate effects.
  4. Custom compression policies: Only default compression policies are available. Domain-specific custom policies cannot be defined yet.

Developer Takeaway

The two most effective ways to reduce agent token costs are:

Compress your inputs. Headroom does this through a single proxy — zero code changes needed. If you can compress tool outputs and logs without modifying your agent, there's no reason not to adopt it.

Make outputs concise. Verbosity steering can reduce output tokens by up to 50%. On models where output costs 5× input, that's literally half the cost.

Headroom solves both with one proxy. Its 78k stars show how sensitive agent developers are to token costs.

Before deploying agents to production, calculate your token costs first. Then apply Headroom compression.