Headroom Configuration Options: Complete Guide to the CCR Pipeline

Headroom configuration options are controlled through a hierarchical HeadroomConfig object that aggregates specialized sub-configs for cache alignment, smart compression, and reversible caching across the compress-cache-retrieve (CCR) pipeline.

The chopratejas/headroom library provides a unified configuration system defined in headroom/config.py that orchestrates how LLM tool outputs are compressed, cached, and retrieved. Understanding these configuration options allows you to tune the trade-off between token usage and context preservation for any LLM provider workload.

Core Configuration Architecture

At the center of Headroom's configuration system is the HeadroomConfig class, which acts as a single hierarchical entry point for the entire compress-cache-retrieve pipeline. Rather than scattering settings across multiple files, Headroom aggregates all behavior into focused sub-configuration objects that control distinct stages of context processing.

Each sub-configuration targets a specific transformation layer, from initial system-prompt normalization to final smart-compression algorithms. This design allows granular tuning without affecting unrelated pipeline stages.

Top-Level Headroom Configuration Options

The HeadroomConfig class in headroom/config.py exposes these primary configuration fields:

Storage and Operating Mode

• store_url (str = "sqlite:///headroom.db"): Defines the location of the persistent SQLite store used for CCR caching and state management.
• default_mode (HeadroomMode = HeadroomMode.AUDIT): Sets the default operating mode for the pipeline, with options including audit, optimize, and simulate.

Pipeline Stage Controllers

These fields accept sub-configuration objects that define specific transformation behaviors:

• smart_crusher (SmartCrusherConfig): Controls the statistical compression algorithm that reduces tool-output arrays while preserving schema integrity.
• cache_aligner (CacheAlignerConfig): Normalizes system prompts by removing dates, high-entropy strings, and inconsistent whitespace to ensure provider-side prefix caching works reliably.
• cache_optimizer (CacheOptimizerConfig): Provides provider-specific optimizations such as Anthropic cache breakpoints and OpenAI prefix-freeze logic.
• ccr (CCRConfig): Manages the "Compress-Cache-Retrieve" system that makes compression reversible by storing original payloads and injecting retrieval markers.
• prefix_freeze (PrefixFreezeConfig): Tracks and freezes already-cached provider prefixes across conversation turns to prevent unnecessary cache invalidation.

Runtime Safety and Extensions

• output_buffer_tokens (int = 4000): Reserves a token budget for the LLM's final response, ensuring the incoming context never exceeds model context limits.
• intercept_tool_results (bool = False): Enables an opt-in hook that can rewrite tool results (such as AST-grep outputs) before they enter the compression pipeline.
• pipeline_extensions (list[Any] = []): Allows injection of custom transforms or observers without forking the SDK.

Sub-Configuration Reference

Each sub-configuration defined in headroom/config.py exposes specific tuning knobs for its domain:

SmartCrusherConfig: Statistical Compression

Defined in headroom/config.py (line 94), this configuration controls how tool output arrays are statistically reduced:

• enabled: Toggles the compression layer.
• min_items_to_analyze: Minimum array size before compression triggers.
• max_items_after_crush: Target size for compressed arrays; increase this value to preserve more critical data.
• variance_threshold: Statistical threshold for outlier detection; lower values retain more outliers.
• relevance: A nested RelevanceScorerConfig object that determines item scoring.

RelevanceScorerConfig: Scoring Algorithm

Nested within SmartCrusherConfig, this controls how items are ranked for retention:

• tier: Scoring algorithm selection (bm25, embedding, or hybrid). The hybrid option provides best overall recall.
• bm25_k1 and bm25_b: BM25 algorithm parameters for term frequency tuning.
• embedding_model: Model used for semantic similarity when tier is set to embedding or hybrid.
• relevance_threshold: Minimum score for item retention; adjusting this threshold makes compression more or less aggressive.

AnchorConfig: Context Preservation

Controls how the compressor preserves critical front and back elements of arrays:

• anchor_budget_pct: Percentage of the array reserved for anchored items.
• min_anchor_slots: Guaranteed minimum number of anchored items.
• search_front_weight and logs_back_weight: Weighting factors for search results versus log streams.
• use_information_density: Enables density-based item selection.

CacheAlignerConfig: Prompt Normalization

Defined in headroom/config.py (line 26), this prepares system prompts for provider caching:

• enabled: Toggles normalization.
• use_dynamic_detector: Enables richer dynamic-content stripping beyond static date patterns.
• entropy_threshold: Controls aggressiveness of high-entropy string removal; tighten this to avoid over-removing tokens.
• normalize_whitespace: Standardizes whitespace patterns that could break cache hits.

CacheOptimizerConfig: Provider Integration

Located at line 68 in headroom/config.py, this handles provider-specific cache mechanics:

• auto_detect_provider: Automatically applies provider-specific optimizations.
• min_cacheable_tokens: Minimum token threshold for cache eligibility; set this above 1024 for LLMs that only cache larger blocks.
• enable_semantic_cache: Enables query-level semantic caching for identical prompt reuse.

CCRConfig: Reversible Caching

Defined at line 93 in headroom/config.py, this makes compression lossless:

• store_ttl_seconds: Time-to-live for stored original payloads; reduce this for short-lived conversations.
• inject_retrieval_marker: Whether to append markers indicating compressed content.
• marker_template: Customizable template for retrieval markers, supporting variables like {original_count}, {compressed_count}, and {hash}.

PrefixFreezeConfig: Cache Persistence

Located at line 42 in headroom/config.py, this manages prefix cache state across turns:

• min_cached_tokens: Minimum token count required to consider a prefix frozen.
• force_compress_threshold: Token savings threshold that must be met before busting an existing cache; raise this on providers with high read discounts (such as Anthropic).

How the Configuration Pipeline Works

When you instantiate a HeadroomClient with a HeadroomConfig, the SDK builds a transformation pipeline that processes context in this order:

1. System-prompt normalization (CacheAlignerConfig) strips dates, timestamps, and high-entropy strings that could prevent cache hits.
2. Provider-specific optimization (CacheOptimizerConfig) injects cache-control hints appropriate for your LLM provider.
3. Tool-output compression (SmartCrusherConfig) analyzes array-type outputs, preserving anchors and relevance-scored items while removing duplicates.
4. Reversible caching (CCRConfig) stores the untouched payload in SQLite and appends a retrieval marker so the LLM can request the full data later.
5. Prefix freeze (PrefixFreezeConfig) monitors the provider's prefix cache across conversation turns, deciding whether to compress the prefix based on cost-benefit analysis.

Practical Configuration Examples

Creating a Custom Configuration

This example shows how to instantiate HeadroomConfig with custom compression and caching settings:

from headroom.config import HeadroomConfig, HeadroomMode, SmartCrusherConfig, RelevanceScorerConfig
from headroom.client import HeadroomClient

# Start from defaults and tweak specific knobs

cfg = HeadroomConfig()
cfg.default_mode = HeadroomMode.OPTIMIZE
cfg.smart_crusher = SmartCrusherConfig(
    max_items_after_crush=30,               # Keep more items than default

    relevance=RelevanceScorerConfig(
        tier="hybrid",                      # Use hybrid BM25 + embedding scoring

        relevance_threshold=0.20,           # More aggressive compression

    ),
)
cfg.cache_aligner.use_dynamic_detector = False   # Use legacy date-only detection

cfg.ccr.store_ttl_seconds = 600                 # Keep cache entries for 10 minutes

# Initialize client with custom configuration

client = HeadroomClient(config=cfg)
response = client.chat(messages=[{"role": "user", "content": "Summarise the last 100 lines of the log file"}])
print(response["content"])

Overriding Settings Per Request

You can override specific configuration values for individual calls using the config_overrides parameter in headroom/client.py:

from headroom.config import RelevanceScorerConfig, SmartCrusherConfig
from headroom.client import HeadroomClient

client = HeadroomClient()

# Build a temporary config that only changes the relevance tier

temp_cfg = SmartCrusherConfig(
    relevance=RelevanceScorerConfig(tier="bm25", relevance_threshold=0.15)
)

response = client.chat(
    messages=[{"role": "user", "content": "Find all TODO comments in the repo"}],
    config_overrides={"smart_crusher": temp_cfg},
)
print(response["content"])

Enabling Reversible CCR Caching

This configuration enables the full CCR pipeline with custom marker templates defined in headroom/ccr/response_handler.py:

from headroom.config import CCRConfig, HeadroomConfig
from headroom.client import HeadroomClient

cfg = HeadroomConfig()
cfg.ccr = CCRConfig(
    enabled=True,
    inject_retrieval_marker=True,
    marker_template="\n[Compressed {original_count}->{compressed_count}. Retrieve via hash={hash}]"
)

client = HeadroomClient(config=cfg)
output = client.chat(messages=[{"role": "user", "content": "List every file changed in the last commit"}])
print(output["content"])

# Output contains: [Compressed 1200->15. Retrieve via hash=ab12cd...]

Key Source Files

Understanding these source files helps you locate specific configuration logic:

• headroom/config.py: Central definitions for HeadroomConfig and all sub-configurations including SmartCrusherConfig, CacheAlignerConfig, and CCRConfig.
• headroom/client.py: SDK entry point that builds the transform pipeline from configuration objects and handles config_overrides merging.
• headroom/transforms/smart_crusher.py: Implements the statistical compression algorithm driven by SmartCrusherConfig settings.
• headroom/transforms/cache_aligner.py: Applies date stripping and entropy-based normalization based on CacheAlignerConfig.
• headroom/ccr/response_handler.py: Injects retrieval markers into responses when CCRConfig.inject_retrieval_marker is enabled.
• headroom/models/config.py: Contains model-specific context limits and defaults referenced by the configuration system.

Summary

• Headroom organizes configuration into a single HeadroomConfig object that aggregates specialized sub-configs for each pipeline stage.
• Top-level options control storage locations (store_url), operating modes (default_mode), and runtime safety (output_buffer_tokens).
• Sub-configurations like SmartCrusherConfig, CacheAlignerConfig, and CCRConfig provide granular control over compression algorithms, caching strategies, and provider integrations.
• Configuration overrides allow per-request customization without modifying global settings by passing dictionaries to the chat() method.
• All definitions reside in headroom/config.py while execution logic is implemented in headroom/client.py and the transforms/ directory.

Frequently Asked Questions

What is the difference between CacheAlignerConfig and CacheOptimizerConfig?

CacheAlignerConfig normalizes system prompts by removing dynamic content like dates and high-entropy strings to ensure provider-side prefix caching works reliably, while CacheOptimizerConfig applies provider-specific optimizations such as Anthropic cache breakpoints or OpenAI prefix-freeze hints. The aligner prepares content for caching, while the optimizer manages the provider's cache mechanics.

How do I make compression less aggressive for critical tool outputs?

Increase the max_items_after_crush value in SmartCrusherConfig to retain more items, lower the variance_threshold to keep more statistical outliers, and adjust the relevance_threshold in RelevanceScorerConfig to be less aggressive. For example, setting max_items_after_crush=50 and relevance_threshold=0.10 preserves significantly more context than the defaults.

Where does Headroom store the original payloads when using CCR?

Headroom stores original payloads in a SQLite database located at the path specified by the store_url configuration option (defaulting to sqlite:///headroom.db). The CCRConfig object controls this behavior, including the store_ttl_seconds setting that determines how long compressed payloads remain retrievable before automatic cleanup.

Can I use Headroom configuration options with custom transformation pipelines?

Yes, the pipeline_extensions list in HeadroomConfig accepts custom transform objects that implement the Headroom transform interface, allowing you to inject custom observers or modifiers without forking the SDK. Additionally, the intercept_tool_results boolean enables hooks for rewriting tool results before they enter the standard compression pipeline.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}