How to Configure Headroom to Exclude Specific Tools from Compression

You can configure Headroom to exclude specific tools from compression using the --exclude-tools CLI flag, the HEADROOM_EXCLUDE_TOOLS environment variable, or by passing an exclude_tools set to the ContentRouter class programmatically.

Headroom is an open-source proxy that optimizes LLM tool call outputs through intelligent compression. To configure Headroom to exclude specific tools from compression, you modify the ContentRouter behavior via command-line arguments, environment configuration, or direct Python API calls, ensuring that designated tools like Read or Glob pass through to the LLM uncompressed.

How ContentRouter Determines Compression Eligibility

The ContentRouter class (implemented in headroom/transforms/content_router.py) acts as the gatekeeper for tool output compression. By default, it references the DEFAULT_EXCLUDE_TOOLS constant defined in headroom/config.py (lines 34-38), which contains a hardcoded set of tool names that typically produce large binary blobs or file contents unsuitable for compression.

When processing a tool call, the router checks whether the tool's ID exists in the exclusion set. If excluded, the router adds the marker router:excluded:tool to the routing log and returns the original output without modification, completely bypassing the standard Compress-Cache-Retrieve (CCR) pipeline.

Three Methods to Configure Tool Exclusion

You can override the default exclusion list through three distinct interfaces, all converging on the exclude_tools configuration field in ContentRouterConfig.

Using the --exclude-tools CLI Flag

The proxy server parses the --exclude-tools flag in headroom/proxy/server.py (lines 3150-3170). The _parse_exclude_tools function splits comma-separated values and merges them with the configuration. This method replaces DEFAULT_EXCLUDE_TOOLS entirely when the flag is non-empty.

# Exclude Read and Glob tools from compression

headroom --exclude-tools Read,Glob

Using the HEADROOM_EXCLUDE_TOOLS Environment Variable

For Docker or Kubernetes deployments, set the HEADROOM_EXCLUDE_TOOLS environment variable (also parsed in headroom/proxy/server.py, lines 3158-3168):

export HEADROOM_EXCLUDE_TOOLS="Read,Search,CustomTool"
headroom

This achieves identical behavior to the CLI flag without modifying startup commands, making it ideal for containerized environments.

Programmatic Configuration via ContentRouter

When using Headroom as a Python library, instantiate ContentRouter with a custom ContentRouterConfig:

from headroom.transforms import ContentRouter, ContentRouterConfig

router = ContentRouter(
    ContentRouterConfig(
        exclude_tools={"MyCustomTool", "LegacyAPI"}
    )
)

result = router.compress("some content")
print(result.routing_log)  # Contains "router:excluded:tool" for excluded tools

This approach (implemented in headroom/transforms/content_router.py, lines 505-508) allows dynamic exclusion lists based on runtime conditions or user preferences.

Internal Implementation Details

Inside ContentRouter._compress() (around lines 1900-1906), the exclusion logic builds a set of tool IDs to skip before processing:

exclude_tools = (
    self.config.exclude_tools
    if self.config.exclude_tools is not None
    else DEFAULT_EXCLUDE_TOOLS
)
excluded_tool_ids = {
    tool_id for tool_id, name in tool_name_map.items() 
    if name in exclude_tools
}

If a tool call's tool_use_id matches an entry in excluded_tool_ids, the compression pipeline halts immediately for that specific output, preserving the raw tool response.

Effects on Downstream Processing

Excluding a tool from compression affects two key downstream behaviors in the Headroom pipeline:

• CCR Markers: Excluded tools do not receive compress:, cache:, or retrieve: markers in the final payload, as they bypass the compression pipeline entirely according to the logic in headroom/transforms/content_router.py.

• Cost Telemetry: The system records exclusion events via the router:excluded:tool marker in headroom/proxy/cost.py (lines 70-78). This enables accurate cost accounting and observability even for uncompressed tool outputs.

Disabling Exclusion Entirely

To subject all tool output to compression—including the default Read and Glob tools—pass an empty string to either configuration method:

# Via CLI

headroom --exclude-tools ""

# Via environment variable

export HEADROOM_EXCLUDE_TOOLS=""
headroom

This sets exclude_tools to an empty set, meaning DEFAULT_EXCLUDE_TOOLS is ignored and no tools receive special treatment.

Summary

• Headroom's ContentRouter controls compression eligibility via the exclude_tools configuration field defined in headroom/transforms/content_router.py.
• Default exclusions (Read, Glob, etc.) live in DEFAULT_EXCLUDE_TOOLS within headroom/config.py.
• Configure exclusions via --exclude-tools CLI flag, HEADROOM_EXCLUDE_TOOLS environment variable, or ContentRouterConfig programmatically.
• Excluded tools bypass CCR markers but still log router:excluded:tool events to headroom/proxy/cost.py for cost tracking.
• Pass an empty string to disable exclusion entirely and compress all tool outputs without exception.

Frequently Asked Questions

What happens if I specify both the CLI flag and the environment variable?

According to the source code in headroom/proxy/server.py, the --exclude-tools CLI flag takes precedence and overrides the HEADROOM_EXCLUDE_TOOLS environment variable. If the flag is omitted, the system falls back to the environment variable, and if neither is set, it uses DEFAULT_EXCLUDE_TOOLS.

Can I exclude custom tools that I've defined myself?

Yes. The exclude_tools set accepts any string tool name. When using the Python API, simply include your custom tool names in the set passed to ContentRouterConfig. The router checks tool names case-sensitively against this list, so ensure the names match exactly what the LLM generates in tool calls.

Why are Read and Glob excluded by default?

These tools typically return large file contents or directory listings that are either already compressed binary data or don't benefit from text-based compression algorithms. The DEFAULT_EXCLUDE_TOOLS constant in headroom/config.py protects these high-volume outputs from unnecessary processing overhead and potential data corruption through text compression.

How can I verify that a tool is actually being excluded?

Check the routing log output from the ContentRouter. When a tool is excluded, the router adds the router:excluded:tool marker to the routing log. You can also inspect the final payload to confirm that CCR markers are absent for that specific tool's output, or query the cost telemetry in headroom/proxy/cost.py which tracks these exclusion events separately from compression events.

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