How Does Headroom SmartCrusher Compress JSON Tool Outputs by 90%?

Jun 3, 2026

Problem

My agent returns a tool output with 1,000 items. It looks like this:

{
    "results": [
        {"id": 1, "status": "ok", "message": "Success"},
        {"id": 2, "status": "ok", "message": "Success"},
        {"id": 3, "status": "ok", "message": "Success"},
        // ... 995 more "ok" results ...
        {"id": 998, "status": "error", "message": "Connection timeout"},
        {"id": 999, "status": "ok", "message": "Success"},
        {"id": 1000, "status": "ok", "message": "Success"}
    ]
}

Sending all 1,000 items to the LLM wastes 45,000 tokens. Truncation is dangerous because the error at item 998 is exactly what the model needs to debug the issue.

What Is SmartCrusher?

SmartCrusher is Headroom’s statistical compressor for JSON arrays. It scores each item across five dimensions, then keeps a representative subset:

First items (30% of budget) — schema and structure
Last items (15% of budget) — recency
Errors — always kept, regardless of budget
Anomalies — items with >2 standard deviations from the mean
Relevance to query — items matching the user’s question

How to Use It

from headroom import SmartCrusher, SmartCrusherConfig

config = SmartCrusherConfig(
    min_tokens_to_crush=200,
    max_items_after_crush=50,
    keep_first=3,
    keep_last=2,
    preserve_errors=True,
    anomaly_std_threshold=2.0,
)

crusher = SmartCrusher(config)
compressed = crusher.crush(tool_output, query="find payment failures")

The result is about 50 items instead of 1,000. Token count drops from 45,000 to roughly 4,500 — a 90% reduction.

What Gets Kept

SmartCrusher factors out constant fields shared by all items. Then it keeps:

The first 3 items (schema)
The last 2 items (recency)
The error at id=998 (unconditional)
A statistical sample of the rest

The LLM still sees a representative distribution, plus every error and anomaly.

Real Numbers

From the Headroom docs, here are typical savings:

Content Type	Token Reduction
JSON arrays of dicts	83-95%
Build/test logs	85-94%
HTML article extraction	~95%

In one real workload, 17,765 tokens of code search results became 1,408 tokens — 92% savings with the same final answer.

I used to truncate at a fixed token limit. The problem:

Item 1-50 might all be “ok” and tell the model nothing
Item 998 has the error but gets dropped
The model asks “Are there any errors?” and I have no answer

SmartCrusher solves this by preserving errors unconditionally and using statistics instead of position.

Performance

Overhead is 1-50ms for typical payloads. That is negligible compared to the LLM API call it precedes.

Summary

In this post, I showed how SmartCrusher compresses JSON arrays by 70-95%. The key point is that it uses statistical sampling plus anomaly preservation, so you cut tokens without dropping the errors the LLM needs.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 Headroom SmartCrusher Documentation
👨‍💻 Headroom GitHub Repository

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!