# What Compression Algorithms Does Headroom Support? Complete Technical Guide

> Explore Headroom's supported compression algorithms including AST preserving code compression ML-based token reduction high-density JSON crushing and more. Optimize your data.

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

---

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

```python
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:

```python
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:

```python
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:

```python
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`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/content_router.py)**: Central router, `CompressionStrategy` enum, and configuration logic
- **[`headroom/transforms/code_compressor.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/code_compressor.py)**: `CodeAwareCompressor` implementation for AST-preserving code compression
- **[`headroom/transforms/kompress_compressor.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/kompress_compressor.py)**: `KompressCompressor` for ML-based plain-text compression
- **[`headroom/transforms/search_compressor.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/search_compressor.py)**: `SearchCompressor` for search result reduction
- **[`headroom/transforms/log_compressor.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/log_compressor.py)**: `LogCompressor` for build/test log trimming
- **[`headroom/transforms/diff_compressor.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/diff_compressor.py)**: `DiffCompressor` for Git diff optimization
- **[`headroom/transforms/html_extractor.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/html_extractor.py)**: `HTMLExtractor` for HTML token reduction
- **[`headroom/transforms/smart_crusher.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/smart_crusher.py)**: `SmartCrusher` for high-density JSON array compression
- **[`headroom/transforms/compression_units.py`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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`](https://github.com/chopratejas/headroom/blob/main/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.