ContentRouterConfig Configuration Options: Complete Guide to Headroom Content Routing

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 (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.

Practical Configuration Examples

Basic Usage with Defaults

Instantiate ContentRouter without arguments to use the default ContentRouterConfig:

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:

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:

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:

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 (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, 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.

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