# How to Configure Per-Tool Compression Profiles in Headroom for Different Tool Outputs

> Learn to configure per-tool compression profiles in Headroom by mapping tool names to compression profiles. Modify global defaults or pass custom profiles at runtime for tailored outputs.

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

---

**Configure per-tool compression profiles by mapping tool names to `CompressionProfile` instances—either by modifying `DEFAULT_TOOL_PROFILES` in [`headroom/config.py`](https://github.com/chopratejas/headroom/blob/main/headroom/config.py) for global changes or by passing a custom `tool_profiles` dictionary to `HeadroomClient` at runtime.**

Headroom supports **per-tool compression profiles** that let you control how aggressively the framework compresses output from individual tools like `Grep`, `Bash`, or `WebFetch`. These profiles are defined in [`headroom/config.py`](https://github.com/chopratejas/headroom/blob/main/headroom/config.py) and consumed by the `ContentRouter` class in [`headroom/transforms/content_router.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/content_router.py) during the compression step. Understanding how to tune these profiles allows you to preserve more context from critical tools while aggressively compressing verbose outputs from others.

## Understanding CompressionProfile Parameters

The `CompressionProfile` class in [`headroom/config.py`](https://github.com/chopratejas/headroom/blob/main/headroom/config.py) encapsulates three tunable parameters that govern how the adaptive compression algorithm selects content:

- **`bias`**: A multiplier applied to the adaptive "K" value. Values **greater than 1.0** produce conservative compression (retaining more items), while values **less than 1.0** produce aggressive compression (retaining fewer items).
- **`min_k`**: The absolute minimum number of items that must be retained, regardless of the adaptive calculation.
- **`max_k`**: An optional hard cap on the number of items retained. When set to `None`, the algorithm relies entirely on statistical analysis.

## Default Profile Architecture

Headroom provides two mechanisms for default profile assignment:

1. **Named Presets**: The `PROFILE_PRESETS` dictionary (lines 259–278 of [`headroom/config.py`](https://github.com/chopratejas/headroom/blob/main/headroom/config.py)) defines three ready-made configurations:
   - `conservative` (bias=1.5, min_k=5)
   - `moderate` (bias=1.0, min_k=3) 
   - `aggressive` (bias=0.7, min_k=3)

2. **Per-Tool Defaults**: The `DEFAULT_TOOL_PROFILES` dictionary (lines 281–292 of [`headroom/config.py`](https://github.com/chopratejas/headroom/blob/main/headroom/config.py)) maps specific tool names to these presets. Any tool not explicitly listed defaults to the `moderate` profile.

When the `ContentRouter` processes tool output—as noted in the comment "# Per-tool compression profiles (tool_name → CompressionProfile)" near line 512 of [`headroom/transforms/content_router.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/content_router.py)—it consults these mappings to determine which profile to apply during the compression execution (see lines 2285–2299).

## Configuration Methods

You can configure per-tool compression profiles either globally by modifying the default mappings or locally by passing custom configurations when instantiating the client.

### Modifying Default Tool Profiles Globally

To change compression behavior for all future invocations, import and modify `DEFAULT_TOOL_PROFILES` before initializing the client. Note that tool names are case-sensitive, so you should map both the canonical class name and lowercase variants:

```python

# my_headroom_config.py

from headroom.config import DEFAULT_TOOL_PROFILES, PROFILE_PRESETS

# Retain more search results by using the conservative preset

DEFAULT_TOOL_PROFILES["Grep"] = PROFILE_PRESETS["conservative"]
DEFAULT_TOOL_PROFILES["grep"] = PROFILE_PRESETS["conservative"]

# Aggressively compress bash output to save tokens

DEFAULT_TOOL_PROFILES["Bash"] = PROFILE_PRESETS["aggressive"]
DEFAULT_TOOL_PROFILES["bash"] = PROFILE_PRESETS["aggressive"]

```

### Supplying Custom Profiles at Runtime

For project-specific configurations, pass a `tool_profiles` dictionary directly to the `HeadroomClient` constructor. This overrides the defaults without modifying global state:

```python
from headroom import HeadroomClient
from headroom.config import CompressionProfile

# Create a custom profile: keep at most 10 items with aggressive bias

custom_bash_profile = CompressionProfile(bias=0.8, min_k=3, max_k=10)

client = HeadroomClient(
    # ... other configuration options ...

    tool_profiles={"Bash": custom_bash_profile, "bash": custom_bash_profile}
)

```

### Adding Profiles for Custom Tools

When extending Headroom with custom tools, register them in `DEFAULT_TOOL_PROFILES` to ensure they receive appropriate compression treatment:

```python
from headroom.config import DEFAULT_TOOL_PROFILES, PROFILE_PRESETS

# Apply aggressive compression to custom database query results

DEFAULT_TOOL_PROFILES["MySQLQuery"] = PROFILE_PRESETS["aggressive"]
DEFAULT_TOOL_PROFILES["mysqlquery"] = PROFILE_PRESETS["aggressive"]

```

## How the ContentRouter Applies Profiles

During the transformation pipeline, the `ContentRouter` executes the following resolution logic:

1. Checks for an explicit profile in the user-supplied configuration (`tool_profiles` parameter).
2. Falls back to `DEFAULT_TOOL_PROFILES` using the tool name as the lookup key.
3. Applies the selected `CompressionProfile` to bias the adaptive K-selection algorithm that determines how many items survive compression.

This resolution occurs in [`headroom/transforms/content_router.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/content_router.py), where the router binds the profile to the compression call based on the current tool context.

## Summary

- **Per-tool compression profiles** are `CompressionProfile` instances that control token retention via `bias`, `min_k`, and `max_k` parameters.
- Default behaviors are defined in [`headroom/config.py`](https://github.com/chopratejas/headroom/blob/main/headroom/config.py) through `PROFILE_PRESETS` and `DEFAULT_TOOL_PROFILES`.
- Modify `DEFAULT_TOOL_PROFILES` to change global defaults, or pass `tool_profiles` to `HeadroomClient` for instance-specific configurations.
- The `ContentRouter` in [`headroom/transforms/content_router.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/content_router.py) applies these profiles during the compression step (around lines 2285–2299).
- Tool name lookups are case-sensitive; map both `ToolName` and `toolname` variants for robustness.

## Frequently Asked Questions

### How do I make Headroom keep more results from the Grep tool?

Create a custom `CompressionProfile` with a bias greater than 1.0 or use the built-in `conservative` preset. Assign this to both `"Grep"` and `"grep"` keys in `DEFAULT_TOOL_PROFILES` or pass it via the `tool_profiles` parameter when constructing `HeadroomClient`. A bias of 1.5 (conservative) significantly increases the number of search results retained compared to the default moderate setting.

### Can I set a hard limit on the number of items a specific tool returns?

Yes, instantiate `CompressionProfile` with the `max_k` parameter set to your desired limit. For example, `CompressionProfile(bias=1.0, min_k=5, max_k=20)` ensures the tool never returns more than 20 items, regardless of the adaptive algorithm's calculation. Pass this profile through the `tool_profiles` dictionary when initializing the client.

### Where does Headroom look up the compression profile for a tool?

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 first checks for user-provided profiles in the configuration, then falls back to `DEFAULT_TOOL_PROFILES` defined in [`headroom/config.py`](https://github.com/chopratejas/headroom/blob/main/headroom/config.py). If no specific mapping exists, the tool uses the `moderate` preset from `PROFILE_PRESETS`. This lookup occurs during the compression phase near lines 2285–2299 of the content router module.

### Why should I map both uppercase and lowercase tool names?

Headroom's tool resolution may refer to tools by their class name (e.g., `"Grep"`) or by a lowercase identifier (e.g., `"grep"`) depending on the execution context. To ensure your compression profile applies consistently, define entries for both variants in your configuration dictionary, as shown in the `DEFAULT_TOOL_PROFILES` implementation in [`headroom/config.py`](https://github.com/chopratejas/headroom/blob/main/headroom/config.py).