# How to Configure Tool-Specific Compression Profiles in Headroom

> Master tool-specific compression profiles in Headroom. Learn to customize compression policies with regex patterns and item limits for optimized transformations. Get started now.

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

---

**You configure tool-specific compression profiles in Headroom by instantiating a custom `CompressionPolicy` with a list of `ToolProfile` objects that map regex patterns to item limits, then passing that policy to the `TransformPipeline` via the `compression_policy` parameter.**

Headroom is an open-source proxy framework that optimizes LLM context windows through intelligent compression. While the system defaults to per-authentication-mode policies, production deployments often need granular control over how individual tools are compressed. This guide demonstrates how to configure tool-specific compression profiles using Headroom's policy architecture as implemented in the `chopratejas/headroom` repository.

## Understanding Headroom's Compression Architecture

Headroom's compression behavior is governed by the `CompressionPolicy` dataclass defined in [`headroom/transforms/compression_policy.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/compression_policy.py). The policy system operates on a per-auth-mode basis, with transforms like `CacheAligner`, `SmartCrusher`, and `ContentRouter` accessing the runtime policy via `self._runtime_compression_policy`.

The pipeline injects this policy into every transform through `kwargs["compression_policy"]`, allowing downstream compressors to adjust their behavior based on the active configuration. By default, the system resolves policies using `policy_for_mode(AuthMode)` or the `resolve_policy(auth_mode)` helper, but you can override this with custom tool-specific mappings.

## Creating Tool-Specific Profiles

Tool-specific profiles allow you to define different compression limits for different tools using regex pattern matching. This is particularly useful when certain tools (like database queries) need higher context retention than others (like Slack searches).

### Define the ToolProfile Structure

While Headroom's core compressors expect a specific profile shape, you define custom profiles using a dataclass that includes a regex pattern, a maximum item limit, and an enable flag. The `get_profile(tool_name: str)` helper in [`headroom/transforms/compression_units.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/compression_units.py) selects the first matching profile from your list.

```python
from dataclasses import dataclass
import re
from typing import List

@dataclass(frozen=True, slots=True)
class ToolProfile:
    """Defines compression behavior for a specific tool or tool group."""
    tool_name_pattern: re.Pattern[str]   # Regex matching the tool identifier

    max_items: int                       # Maximum items the compressor retains

    enabled: bool = True                 # Gate to disable compression entirely

```

### Build Profile Lists with Fallbacks

Create a prioritized list where the first matching pattern wins. Include a catch-all entry at the end to define default behavior for unmatched tools.

```python
custom_profiles: List[ToolProfile] = [
    ToolProfile(re.compile(r"slack", re.I), max_items=25),
    ToolProfile(re.compile(r"database|sql", re.I), max_items=30),
    ToolProfile(re.compile(r"github", re.I), max_items=20),
    # Fallback profile matches any tool name

    ToolProfile(re.compile(r".*"), max_items=20),
]

```

## Attaching Profiles to the Compression Policy

The `CompressionPolicy` dataclass does not include a `profiles` field by default, so you attach your custom list as a dynamic attribute. This pattern is safe because the MCP compressor reads the attribute directly from the policy object.

### Instantiate and Customize the Policy

Start with a base policy using `policy_for_mode()`, then attach your profile list using `setattr()`.

```python
from headroom.transforms.compression_policy import CompressionPolicy, policy_for_mode
from headroom.types import AuthMode

# Start with PAYG or SUBSCRIPTION base policy

base_policy = policy_for_mode(AuthMode.PAYG)

# Build custom policy preserving core fields

custom_policy = CompressionPolicy(
    live_zone_only=base_policy.live_zone_only,
    cache_aligner_enabled=base_policy.cache_aligner_enabled,
    volatile_token_threshold=base_policy.volatile_token_threshold,
    max_lossy_ratio=base_policy.max_lossy_ratio,
    toin_read_only=base_policy.toin_read_only,
)

# Attach tool-specific profiles (not a dataclass field, but expected by compressor)

setattr(custom_policy, "profiles", custom_profiles)

```

### Configure the Transform Pipeline

Pass the customized policy to `TransformPipeline` during initialization. The pipeline forwards this policy to all transforms via their `kwargs`.

```python
from headroom.transforms.pipeline import TransformPipeline
from headroom.transforms.smart_crusher import SmartCrusher

pipeline = TransformPipeline(
    transforms=[
        SmartCrusher(),
        # Additional transforms...

    ],
    compression_policy=custom_policy,
)

```

When the pipeline processes a request, transforms access `self._runtime_compression_policy` (populated from `kwargs["compression_policy"]`) to determine compression behavior. The MCP compressor calls `get_profile(tool_name)`—passing the tool name from request metadata—to retrieve the appropriate `ToolProfile` and apply its `max_items` limit.

## Alternative Policy Resolution Methods

You can override policy selection without modifying pipeline construction by using environment variables or manual resolution.

**Environment Variable Approach**: Set `HEADROOM_PROXY_AUTH_MODE_POLICY_ENFORCEMENT=disabled` to force PAYG-style policies for all tools, bypassing the automatic resolution logic.

**Manual Resolution**: Call `headroom.transforms.compression_policy.resolve_policy(auth_mode)` directly and substitute the returned object with your custom policy before passing it to transforms.

## Complete Working Example

This end-to-end example demonstrates building a per-tool profile list and executing the pipeline:

```python
import re
from dataclasses import dataclass
from typing import List

from headroom.transforms.compression_policy import CompressionPolicy, policy_for_mode
from headroom.transforms.pipeline import TransformPipeline
from headroom.transforms.smart_crusher import SmartCrusher
from headroom.types import AuthMode

# 1. Define tool-specific profiles

@dataclass(frozen=True, slots=True)
class ToolProfile:
    tool_name_pattern: re.Pattern[str]
    max_items: int
    enabled: bool = True

profiles = [
    ToolProfile(re.compile(r"slack", re.I), max_items=25),
    ToolProfile(re.compile(r"database|sql", re.I), max_items=30),
    ToolProfile(re.compile(r"github", re.I), max_items=20),
    ToolProfile(re.compile(r".*"), max_items=20),  # fallback

]

# 2. Create custom compression policy

base = policy_for_mode(AuthMode.PAYG)
custom_policy = CompressionPolicy(
    live_zone_only=base.live_zone_only,
    cache_aligner_enabled=base.cache_aligner_enabled,
    volatile_token_threshold=base.volatile_token_threshold,
    max_lossy_ratio=base.max_lossy_ratio,
    toin_read_only=base.toin_read_only,
)
setattr(custom_policy, "profiles", profiles)

# 3. Initialize pipeline with custom policy

pipeline = TransformPipeline(
    transforms=[SmartCrusher()],
    compression_policy=custom_policy,
)

# 4. Execute with specific tool name

# messages = [...]  # Your message list

# tokenizer = tokenizer_factory()

# result = pipeline.apply(messages, tokenizer, tool_name="mcp__slack__search")

```

## Summary

- **Tool-specific compression** in Headroom relies on creating `ToolProfile` objects with regex patterns and `max_items` limits.
- **Policy attachment** requires setting the `profiles` attribute on a `CompressionPolicy` instance (via `setattr`) because it is not a native dataclass field.
- **Pipeline injection** occurs through the `compression_policy` parameter in `TransformPipeline`, which propagates to all transforms via `kwargs`.
- **Profile selection** happens at runtime via `get_profile(tool_name: str)` in [`headroom/transforms/compression_units.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/compression_units.py), using the first matching regex pattern.
- **File locations**: Policy logic lives in [`headroom/transforms/compression_policy.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/compression_policy.py), profile utilities in [`headroom/transforms/compression_units.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/compression_units.py), and pipeline orchestration in [`headroom/transforms/pipeline.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/pipeline.py).

## Frequently Asked Questions

### Where is the CompressionPolicy dataclass defined?

The `CompressionPolicy` dataclass is defined in [`headroom/transforms/compression_policy.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/compression_policy.py). This file also contains the `policy_for_mode()` and `resolve_policy()` helper functions that the system uses to select default policies based on authentication modes.

### How does the pipeline pass the compression policy to transforms?

The `TransformPipeline` class (in [`headroom/transforms/pipeline.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/pipeline.py)) stores the policy in `self._runtime_compression_policy` and injects it into each transform via the `kwargs["compression_policy"]` argument. Transforms like `SmartCrusher` and `ContentRouter` then read this value to adjust their compression behavior.

### Can I disable compression for specific tools while keeping it enabled for others?

Yes. Set `enabled=False` in the `ToolProfile` for tools you want to exclude from compression. When `get_profile(tool_name)` returns a profile with `enabled=False`, the compressor bypasses compression for that request while continuing to process other tools normally.

### What is the difference between AuthMode.PAYG and AuthMode.SUBSCRIPTION policies?

`AuthMode.PAYG` (Pay As You Go) and `AuthMode.SUBSCRIPTION` represent different billing tiers that trigger distinct default `CompressionPolicy` configurations. `policy_for_mode(AuthMode)` returns a policy with settings optimized for each tier's cost and performance characteristics, which you can then customize with tool-specific profiles as shown above.