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

Configure per-tool compression profiles by mapping tool names to CompressionProfile instances—either by modifying DEFAULT_TOOL_PROFILES in 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 and consumed by the ContentRouter class in 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 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) 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) 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—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:

# 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:

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:

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, 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 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 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, the router first checks for user-provided profiles in the configuration, then falls back to DEFAULT_TOOL_PROFILES defined in 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.

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