What Compression Algorithms Does Headroom Support? Complete Technical Guide

Headroom supports nine distinct compression strategies including AST-preserving code compression, ML-based token reduction, high-density JSON crushing, and specialized handlers for logs, diffs, HTML, and search results.

Headroom (chopratejas/headroom) is an open-source text compression library that implements a strategy-based router to automatically select the optimal algorithm for different content types. Understanding what compression algorithms Headroom supports is essential for developers working with source code, JSON data, build logs, or mixed content formats.

How the Strategy-Based Router Works

Headroom's compression system centers on the ContentRouter class defined in headroom/transforms/content_router.py. This router uses the CompressionStrategy enum to route text to specialized compressors based on automatic content detection via the _detect_content method. The ContentRouterConfig class manages which strategies are enabled, with all compression-compatible strategies active by default except CODE_AWARE.

Complete List of Compression Algorithms

CODE_AWARE: AST-Preserving Source Code Compression

The CODE_AWARE strategy invokes the CodeAwareCompressor class from headroom/transforms/code_compressor.py. This algorithm preserves Abstract Syntax Tree (AST) integrity while compressing source code, making it safe for programming languages where structure must remain intact. Note that this strategy is disabled by default (enable_code_aware: False) and must be explicitly enabled in the configuration.

SMART_CRUSHER: High-Density JSON Array Compression

The SMART_CRUSHER strategy utilizes the SmartCrusher implementation in headroom/transforms/smart_crusher.py. This algorithm specializes in high-density compression of JSON arrays, significantly reducing payload size for API responses and data exports while maintaining data integrity.

SEARCH: Grep-Style Result Reduction

The SEARCH strategy employs the SearchCompressor from headroom/transforms/search_compressor.py. Designed for grep and ripgrep-style output, this algorithm reduces search result volumes while preserving match context and line references.

LOG: Build and Test Log Trimming

The LOG strategy uses the LogCompressor class in headroom/transforms/log_compressor.py. This algorithm intelligently trims build and test logs, preserving error lines and critical failure messages while removing verbose informational output.

KOMPRESS: ML-Based Plain Text Token Compression

The KOMPRESS strategy implements the KompressCompressor from headroom/transforms/kompress_compressor.py. This general-purpose, ML-based algorithm performs token-level compression on plain text. The TEXT strategy serves as a fallback alias that routes generic plain-text content to KOMPRESS when no specific patterns are detected.

DIFF: Git Diff Compression

The DIFF strategy utilizes the DiffCompressor from headroom/transforms/diff_compressor.py. This algorithm specifically optimizes Git diff output, removing redundant context while preserving line changes and file metadata.

HTML: HTML Token Reduction

The HTML strategy employs the HTMLExtractor class from headroom/transforms/html_extractor.py. This algorithm extracts meaningful content from HTML documents before applying compression, reducing tag overhead and script noise.

MIXED: Multi-Content Type Handling

The MIXED strategy enables the router to split heterogeneous content into sections and apply algorithm-specific compression to each segment. When content contains code, JSON, and prose together, the router processes each section with the appropriate specialized compressor.

PASSTHROUGH: No-Compression Fallback

The PASSTHROUGH strategy returns content unchanged when the router determines compression is not worthwhile. This occurs when content is too small, protected by configuration flags, or falls below compression efficiency thresholds.

Algorithm Selection and Configuration

The ContentRouter automatically selects compression algorithms through content detection. The _detect_content method analyzes input text to identify patterns matching code, JSON, HTML, logs, or diff formats. By default, the router enables all compression-compatible strategies except CODE_AWARE, which requires explicit activation via ContentRouterConfig with enable_code_aware: True.

Practical Code Examples

Automatic Algorithm Selection

Let the router automatically detect content type and select the optimal algorithm:

from headroom.transforms import ContentRouter

router = ContentRouter()
result = router.compress(my_text)          # `my_text` can be code, JSON, logs, etc.

print(result.strategy_used)               # e.g. CompressionStrategy.KOMPRESS

print(result.compressed)                  # compressed output

Forcing a Specific Compression Algorithm

Bypass automatic detection to use a specific compressor:

from headroom.transforms import ContentRouter, CompressionStrategy

router = ContentRouter()

# Force the ML‑based plain‑text compressor

result = router.compress(my_text, strategy=CompressionStrategy.KOMPRESS)
print(result.compressed)

Compressing JSON with SmartCrusher

Explicitly use the JSON-specific compression strategy:

from headroom.transforms import ContentRouter, CompressionStrategy

router = ContentRouter()
json_array = '[{"id":1,"value":"a"}, {"id":2,"value":"b"}]'
result = router.compress(json_array, strategy=CompressionStrategy.SMART_CRUSHER)
print(result.compressed)   # compressed JSON representation

Direct Low-Level Compressor Access

Instantiate compressors directly for specialized pipelines:

from headroom.transforms.kompress_compressor import KompressCompressor

compressor = KompressCompressor()
compressed = compressor.compress(long_paragraph).compressed
print(compressed)

Key Implementation Files

The compression algorithms are implemented across the following source files:

• headroom/transforms/content_router.py: Central router, CompressionStrategy enum, and configuration logic
• headroom/transforms/code_compressor.py: CodeAwareCompressor implementation for AST-preserving code compression
• headroom/transforms/kompress_compressor.py: KompressCompressor for ML-based plain-text compression
• headroom/transforms/search_compressor.py: SearchCompressor for search result reduction
• headroom/transforms/log_compressor.py: LogCompressor for build/test log trimming
• headroom/transforms/diff_compressor.py: DiffCompressor for Git diff optimization
• headroom/transforms/html_extractor.py: HTMLExtractor for HTML token reduction
• headroom/transforms/smart_crusher.py: SmartCrusher for high-density JSON array compression
• headroom/transforms/compression_units.py: Provider-agnostic unit handling used by the router

Summary

• Headroom supports ten compression strategies defined in the CompressionStrategy enum in headroom/transforms/content_router.py
• The ContentRouter class automatically selects optimal algorithms based on content type detection, defaulting to KOMPRESS for plain text
• CODE_AWARE compression is disabled by default and must be explicitly enabled via ContentRouterConfig
• Specialized algorithms exist for JSON (SMART_CRUSHER), logs (LOG), diffs (DIFF), HTML (HTML), and search results (SEARCH)
• The MIXED strategy enables handling of heterogeneous content by applying multiple algorithms to different sections

Frequently Asked Questions

Can I force Headroom to use a specific compression algorithm?

Yes. While the ContentRouter automatically selects algorithms based on content detection, you can bypass this by passing the strategy parameter to the compress() method. For example, use strategy=CompressionStrategy.KOMPRESS to force the ML-based plain-text compressor regardless of content type.

Which compression algorithm does Headroom use by default for plain text?

According to the source code in headroom/transforms/content_router.py, the router defaults to the KOMPRESS strategy for generic plain-text content. The TEXT strategy is essentially an alias that falls back to KOMPRESS when no specific content patterns are detected.

Is the CODE_AWARE compression strategy enabled by default?

No. The CODE_AWARE strategy, which uses CodeAwareCompressor for AST-preserving source code compression, is disabled by default (enable_code_aware: False). You must explicitly enable it through ContentRouterConfig if you want the router to consider code-specific compression for detected source files.

How does Headroom handle mixed content containing code, JSON, and prose?

The MIXED strategy enables the router to split content into distinct sections and apply the most appropriate compression algorithm to each segment. This allows Headroom to compress code blocks with CODE_AWARE, JSON arrays with SMART_CRUSHER, and prose sections with KOMPRESS within a single document.

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