# Headroom Configuration Options: Complete Guide to the CCR Pipeline

> Explore Headroom configuration options in this comprehensive guide to the CCR pipeline. Learn about cache alignment, smart compression, and reversible caching with HeadroomConfig.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: deep-dive
- Published: 2026-06-12

---

**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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/headroom/config.py) exposes specific tuning knobs for its domain:

### SmartCrusherConfig: Statistical Compression

Defined in [`headroom/config.py`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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:

```python
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`](https://github.com/chopratejas/headroom/blob/main/headroom/client.py):

```python
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`](https://github.com/chopratejas/headroom/blob/main/headroom/ccr/response_handler.py):

```python
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`](https://github.com/chopratejas/headroom/blob/main/headroom/config.py)**: Central definitions for `HeadroomConfig` and all sub-configurations including `SmartCrusherConfig`, `CacheAlignerConfig`, and `CCRConfig`.
- **[`headroom/client.py`](https://github.com/chopratejas/headroom/blob/main/headroom/client.py)**: SDK entry point that builds the transform pipeline from configuration objects and handles `config_overrides` merging.
- **[`headroom/transforms/smart_crusher.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/smart_crusher.py)**: Implements the statistical compression algorithm driven by `SmartCrusherConfig` settings.
- **[`headroom/transforms/cache_aligner.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/cache_aligner.py)**: Applies date stripping and entropy-based normalization based on `CacheAlignerConfig`.
- **[`headroom/ccr/response_handler.py`](https://github.com/chopratejas/headroom/blob/main/headroom/ccr/response_handler.py)**: Injects retrieval markers into responses when `CCRConfig.inject_retrieval_marker` is enabled.
- **[`headroom/models/config.py`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/headroom/config.py) while execution logic is implemented in [`headroom/client.py`](https://github.com/chopratejas/headroom/blob/main/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.