# ContentRouterConfig Configuration Options: Complete Guide to Headroom Content Routing

> Explore the ContentRouterConfig options in Headroom. Discover over 20 parameters for feature toggles, compression, content protection, and routing behavior to optimize your content delivery.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: api-reference
- Published: 2026-06-07

---

**The `ContentRouterConfig` dataclass exposes over 20 tunable parameters that control feature toggles, compression thresholds, content protection policies, and tool-specific routing behaviors for the Headroom content router.**

The `ContentRouterConfig` class serves as the central configuration hub for the intelligent routing logic in the `chopratejas/headroom` repository. Defined in [`headroom/transforms/content_router.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/content_router.py) (lines 219–515), this dataclass determines how the router processes mixed content payloads, selects compression strategies, and protects critical context from modification. All configuration options ship with sensible defaults while allowing granular customization for specific workloads.

## Feature Toggle Options

The router uses boolean flags to laz-load specific compressor implementations. Disabling a feature forces an automatic fallback to the generic **Kompress** strategy.

- **`enable_kompress`** (`bool`, default: `True`): Activates the modern BERT-based token compressor (Kompress). This is the primary compression engine for general text content.
- **`enable_code_aware`** (`bool`, default: `False`): Enables AST-based code compression. When disabled, source code falls back to Kompress processing.
- **`enable_smart_crusher`** (`bool`, default: `True`): Enables JSON-array compression via SmartCrusher, optimized for structured data payloads.
- **`enable_search_compressor`** (`bool`, default: `True`): Activates specialized compression for search-result blocks.
- **`enable_log_compressor`** (`bool`, default: `True`): Enables build and test log compression for CI/CD output.
- **`enable_html_extractor`** (`bool`, default: `True`): Extracts and compresses plain-text from HTML payloads, removing markup overhead.
- **`enable_image_optimizer`** (`bool`, default: `True`): Optimizes image tokens through down-sampling and other image-specific reductions.

## Routing and Strategy Selection

These parameters shape the decision tree in `_determine_strategy` and `_compress_mixed`, controlling how the router classifies and segments incoming content.

- **`prefer_code_aware_for_code`** (`bool`, default: `False`): When `True`, the router prefers the CodeAware compressor over Kompress for source-code sections, even if both are enabled.
- **`mixed_content_threshold`** (`int`, default: `2`): The minimum number of distinct content types required before the router treats a payload as "mixed" and splits it into individual `ContentSection` objects for separate processing.
- **`min_section_tokens`** (`int`, default: `20`): The smallest token count a section must contain to be considered for compression. Sections below this threshold pass through unchanged.
- **`fallback_strategy`** (`CompressionStrategy`, default: `CompressionStrategy.KOMPRESS`): The default compression strategy applied when no specific compressor matches the detected content type.

## Content Protection Settings

Protection flags prevent compression of content likely needed for immediate analysis or required to maintain caching semantics.

- **`skip_user_messages`** (`bool`, default: `True`): Ensures the user's original prompt is never compressed, preserving the subject of analysis in its original form.
- **`protect_recent_code`** (`int`, default: `4`): Specifies the number of most-recent messages whose code sections are exempt from compression, maintaining context recency.
- **`protect_analysis_context`** (`bool`, default: `True`): Detects intents like "analyze" or "review" and protects associated code blocks from compression to preserve analytical context.
- **`protect_recent_reads_fraction`** (`float`, default: `0.0`): Fraction of recent read-tool outputs to protect from compression. A value of `0.0` protects all recent reads, while `1.0` would protect none.
- **`compress_assistant_text_blocks`** (`bool`, default: `False`): When enabled, compresses assistant-generated text blocks. This affects cache-control behavior and should be used cautiously with streaming responses.

## Compression Thresholds and Ratios

These settings influence the `CompressionCache` acceptance logic based on token-saving ratios and minimum size requirements.

- **`min_chars_for_block_compression`** (`int`, default: `500`): The minimum character length a text or tool-result block must reach before the router attempts compression. Blocks shorter than this bypass compression overhead.
- **`min_ratio_relaxed`** (`float`, default: `0.85`): The minimum compression ratio accepted when the context window is mostly empty. Higher values enforce more conservative compression during low-pressure scenarios.
- **`min_ratio_aggressive`** (`float`, default: `0.65`): The minimum compression ratio accepted when the context window nears capacity. Lower values permit tighter compression when token pressure is high.

## CCR and Metadata Handling

Configure the Compress-Cache-Retrieve (CCR) system for reversible compression and tag preservation.

- **`ccr_enabled`** (`bool`, default: `True`): Enables CCR marker injection, allowing compressed payloads to be reversibly decompressed later.
- **`ccr_inject_marker`** (`bool`, default: `True`): When CCR is active, inserts retrieval markers into compressed payloads to facilitate exact reconstruction.
- **`compress_tagged_content`** (`bool`, default: `False`): Determines XML-style tag handling. When `True`, only the tag markers (`<custom-tag>`) are protected, allowing compression of inner text. When `False`, the entire tagged block is protected.

## Tool-Specific Configuration

Fine-tune compression behavior for specific tool outputs and external integrations.

- **`exclude_tools`** (`set[str] | None`, default: `None`): Explicit list of tool names whose output passes through unmodified. Falls back to `DEFAULT_EXCLUDE_TOOLS` when not specified.
- **`tool_profiles`** (`dict[str, Any] | None`, default: `None`): Per-tool compression profiles allowing fine-grained tuning of compression behavior per tool. Uses `DEFAULT_TOOL_PROFILES` when unspecified.
- **`read_lifecycle`** (`ReadLifecycleConfig`, default: default constructed): Configuration for stale and superseded read detection, managed through [`headroom/config.py`](https://github.com/chopratejas/headroom/blob/main/headroom/config.py).

## Practical Configuration Examples

### Basic Usage with Defaults

Instantiate `ContentRouter` without arguments to use the default `ContentRouterConfig`:

```python
from headroom.transforms import ContentRouter

router = ContentRouter()
result = router.compress(large_text_block)
print(result.strategy_used)  # CompressionStrategy.KOMPRESS

```

### Disable HTML Extraction and Enable Code-Aware Compression

Configure the router to process code via AST analysis while stripping HTML handling:

```python
from headroom.transforms import ContentRouter, ContentRouterConfig, CompressionStrategy

config = ContentRouterConfig(
    enable_code_aware=True,
    enable_html_extractor=False,
    prefer_code_aware_for_code=True,
    min_section_tokens=30,
    protect_recent_code=0,  # Compress all historical code

    fallback_strategy=CompressionStrategy.KOMPRESS,
)

router = ContentRouter(config=config)

```

### Tune Compression Ratios for High-Volume Contexts

Adjust ratio thresholds when operating near token limits:

```python
config = ContentRouterConfig(
    protect_recent_reads_fraction=0.2,  # Protect 20% of recent reads

    min_ratio_relaxed=0.90,             # Conservative when context empty

    min_ratio_aggressive=0.70,          # Aggressive when near capacity

)

router = ContentRouter(config=config)

```

### Exclude Specific Tools from Processing

Prevent compression of sensitive tool outputs:

```python
config = ContentRouterConfig(
    exclude_tools={"git_diff", "file_search", "security_audit"},
)

router = ContentRouter(config=config)

```

## Summary

- **`ContentRouterConfig`** centralizes all routing parameters in [`headroom/transforms/content_router.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/content_router.py) (lines 219–515), functioning as the primary configuration interface for the Headroom compression pipeline.
- **Feature toggles** (`enable_*` fields) control lazy-loading of specialized compressors including Kompress, SmartCrusher, and CodeAware.
- **Protection settings** preserve user messages, recent code context, and analysis-critical content from compression to maintain conversational coherence.
- **Threshold parameters** (`min_section_tokens`, `min_chars_for_block_compression`) filter out content too small to benefit from compression overhead.
- **Tool-specific options** (`exclude_tools`, `tool_profiles`) provide per-tool overrides for specialized workflows.

## Frequently Asked Questions

### What is the default fallback strategy when no compressor matches a content type?

According to the source code in [`headroom/transforms/content_router.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/content_router.py), the default `fallback_strategy` is `CompressionStrategy.KOMPRESS`. When the router cannot identify a specific content type or when the matched compressor is disabled, it automatically falls back to this BERT-based token compressor.

### How does the `protect_recent_code` setting work?

The `protect_recent_code` integer specifies how many of the most recent messages containing code blocks remain uncompressed. With the default value of `4`, the router preserves the code sections in the last four messages while allowing compression of older code history. Setting this to `0` removes protection and allows compression of all historical code sections.

### What distinguishes `min_ratio_relaxed` from `min_ratio_aggressive`?

The `min_ratio_relaxed` threshold (default `0.85`) applies when the context window has abundant space, requiring high compression quality to justify the processing overhead. Conversely, `min_ratio_aggressive` (default `0.65`) activates when the context nears capacity, accepting lower compression ratios to relieve token pressure. The router automatically selects the appropriate threshold based on current context utilization.

### How do I completely disable compression for specific tool outputs?

Use the `exclude_tools` parameter to pass a set of tool names that should bypass compression entirely. For example, setting `exclude_tools={"git_diff", "search_results"}` ensures these tool outputs pass through unmodified. If `exclude_tools` remains `None`, the router falls back to the `DEFAULT_EXCLUDE_TOOLS` defined in the configuration module.