Headroom token compression is an open source layer that shrinks tool outputs, logs, files and RAG chunks before they reach the LLM. Its project reports 20% fewer tokens for coding agents and 60 to 95% fewer tokens for JSON, with the same answers. You put it between your agent and the model, so the prompt gets cheaper and the model sees less noise.
Your agent (Creator OS MCP tools, SEO writer, comment bot)
|
| raw tool output: timelines, comment threads,
| past posts, ad report JSON
v
+-------------------------------+
| Headroom |
| library call or proxy |
| compress, keep meaning |
+-------------------------------+
|
| smaller prompt, same facts
v
+-------------------------------+
| LLM (Claude, GPT, local) |
+-------------------------------+
|
v
Answers, replies, drafts, reportsWhat is headroom token compression for LLM agents?
It is a pre-processing step, not a model change: the raw data stays intact and only the copy sent to the model gets smaller.
Agents spend most of their tokens on things the model did not ask for. A get_post_analytics call returns every metric for every post. A list_comments call returns full comment objects with ids, timestamps and profile URLs. A RAG lookup returns whole past posts when one paragraph would answer the question. Headroom strips the boilerplate and keeps the parts that carry meaning, so the same question produces the same answer from a shorter prompt.
Three properties matter for an agent:
- Lossless in intent, not in bytes. The facts survive. Keys the model never reads do not.
- Deterministic. The same input compresses the same way each run, so you can cache and diff prompts.
- Deployable two ways. As a library you call in code, or as a proxy that sits in front of your model endpoint.
It is model agnostic. It works with Claude models such as Opus 5.5 or Haiku 4.5, with GPT, and with anything behind an OpenAI compatible endpoint. Creator OS does not ship its own model, and Headroom does not either. Both sit next to whichever model you already run.
How much do tokens actually cost your SEO agent, comment agent, and social agent?
The cost is not in the prompt you write by hand. It is in the tool results your agent pastes back in on every turn.
Take three agents you can build today on Creator OS:
| Agent | What it reads | Where tokens go |
|---|---|---|
| SEO blog agent | blog_create_article, past articles, keyword notes |
Long HTML drafts and full past articles pulled in as RAG chunks |
| Comment agent | list_comments, get_post_analytics, past replies |
Comment objects with ids, timestamps and profile fields |
| Social agent | Timelines, daily metrics, best time to post | Per-day metric rows across every platform |
Run the math on one loop. An agent that checks comments every 15 minutes does 96 cycles a day. If each cycle feeds 40 comment objects at roughly 120 tokens each, that is about 4,800 input tokens per cycle and 460,000 tokens a day before the agent writes a single reply. Add analytics and DMs and you cross a million input tokens a day on one account. Compressing JSON at the low end of the reported range, 60%, removes about 276,000 of those tokens.
Two facts keep this honest. First, prompt caching already discounts repeated prefixes, so measure your real bill before you optimize. Second, most of the remaining waste is structural, not semantic. You are paying for field names the model ignores. Headroom removes exactly that.
How does Headroom cut 60-95% of JSON tokens without changing answers?
JSON is the easiest target because most of its bytes are repeated keys, quoting and nesting that the model can reconstruct from the schema.
Here is a realistic slice of an ad report from the Creator OS ads tools, the kind ads:overview or ads:analytics returns:
[
{ "ad_id": "ad_8f21", "account_id": "acc_44",
"campaign": { "id": "cmp_09", "name": "Spring boost",
"objective": "engagement", "status": "active" },
"metrics": { "impressions": 18400, "clicks": 412,
"spend": 96.40, "currency": "USD" },
"date": "2026-02-03", "platform": "instagram" },
{ "ad_id": "ad_8f22", "account_id": "acc_44",
"campaign": { "id": "cmp_09", "name": "Spring boost",
"objective": "engagement", "status": "active" },
"metrics": { "impressions": 9200, "clicks": 188,
"spend": 48.10, "currency": "USD" },
"date": "2026-02-03", "platform": "instagram" }
]Two rows already repeat the campaign block and the account id. At 200 rows, the repetition dwarfs the numbers. Compression drops repeated keys, hoists shared values once, and keeps the metric tuples, so the model still sees 18,400 impressions and $96.40 spend on ad_8f21. It reads the table instead of the envelope.
Same idea for a comment thread: keep the text, author handle and timestamp, drop internal ids the model never uses for a reply. A RAG chunk of a past blog post keeps the claim and the example, drops the wrapper markup and navigation. The answer does not change because the answer was never built from the wrapper.
You can check the claim on your own data before you trust it. Compress a batch, send both versions to the model with the same question, and compare outputs. That test is the whole point of the next section.
How to add Headroom to your RAG pipeline and tool outputs
Wire it in at two points: where your agent receives tool results, and where your retriever returns chunks.
- Compress tool output before it enters the message history. Every MCP tool result from Creator OS, such as
get_post_analytics,list_commentsorget_daily_metrics, is JSON. Pass it through Headroom, then append the compressed form. - Compress RAG chunks at retrieval time. A post you wrote six months ago becomes a shorter snippet with the same argument.
- Leave the source of truth full size. Compress the copy sent to the model. Keep the original in your database so writes, webhooks and audits use complete records.
# inside your agent loop, after a tool call returns
raw = creatoros_tool("get_post_analytics", post_id=post_id)
small = headroom.compress(raw, kind="json")
messages.append({"role": "tool", "content": small})The pattern works the same with the Creator OS CLI piping into your own script, or with the MCP server in Claude, Cursor or Windsurf, where your client controls the message history. If you want a working example of a loop that reads comments and replies in your voice, the guide on letting an agent reply to Instagram comments in your voice walks through the tool calls. Kevin also demos these loops on the KevBuildsApps YouTube channel.
One caution: compress after the model has decided what to do, not before. If your agent needs an exact post_ or cmt_ id to call the next tool, keep the ids. Ids are opaque typed tokens, and a stripped id breaks the chain.
Library vs proxy: which Headroom mode should your agent use?
Pick the library when you own the agent code. Pick the proxy when you do not.
| Library | Proxy | |
|---|---|---|
| Where it runs | Inside your process, called on tool results and chunks | As a service in front of the model endpoint |
| Control | Per call, per data type, easy to tune | One endpoint, applies to every request |
| Setup | Add the dependency and a few lines | Point your base URL at the proxy |
| Best for | Custom agents, cron jobs, RAG in your stack | Third party clients, MCP hosts, quick trials |
| Debugging | Log raw and compressed side by side | Log at the proxy boundary |
A practical split: run the library in the agent that drafts posts and replies, where you know each payload type. Run the proxy for anything you cannot edit, such as a desktop AI client pointed at a model. Both give the same compression on the same input.
What breaks when you compress context, and how to test for it
Compression breaks when the model needed the part you removed, and the fix is a test suite that compares answers, not a hunch.
The usual failures:
- Lost identifiers. The agent cannot call the next tool because the id is gone.
- Lost ordering. A comment thread flattened out of sequence changes what a reply should say.
- Lost units and currency. Spend of 96.40 with the currency dropped reads wrong in a summary.
- Lost negatives. A field that said
falseor a metric that was zero disappears, and the model assumes the opposite.
Test it like a regression suite. Build 20 to 50 real prompts from your own history. Run each one against raw context and compressed context on the same model. Score the answers on the facts you care about: correct post, correct number, correct tone. Anything that shifts is a field you must keep. Keep the raw payload logged so failures are reproducible.
Creator OS helps here with validate:post-length and check_caption_length for the output side, and with webhooks like post.published so you can confirm what actually went out. Those checks do not test compression, but they catch the downstream damage when an answer drifts.
Can a comment agent and SNS agent stay affordable at daily volume?
Yes, if you compress the reading side and cache the writing side, and you measure both.
Split the bill in two. Input tokens are the reading side: timelines, threads, RAG, ad JSON. That is where compression pays. Output tokens are the writing side: replies, captions, drafts. You cut those with tighter prompts, not compression, and by drafting once and editing rather than regenerating.
A workable daily setup for one account:
- Compress every tool result before it enters the history.
- Keep a stable system prompt so prompt caching hits.
- Run comment checks on a schedule, not in a tight loop. The CLI gives you
creatoros automations:createwith a cron schedule and a skill name. - Log tokens per cycle so a spike is visible the day it happens.
When you want a ready harness, the open source Social Agents project runs your socials on Creator OS and handles posting, comment replies, DMs and reporting. Watch the launch video for the walkthrough. Pair it with Headroom on the read path and the per-account cost drops without touching what the agent says.
Two cost notes that are easy to forget. WhatsApp template deliveries are billed by Meta to your own WhatsApp Business account, and ad spend is billed by each network to your own ad account. Compression does not change either, so budget them separately.
FAQ
What is the best way to reduce LLM tokens in an AI agent?
Compress tool outputs and RAG chunks before they reach the model, then cache the stable part of your prompt. In practice that means passing JSON results such as analytics and comment lists through Headroom, keeping ids and units, and sending short chunks instead of whole documents. Measure before and after on your own traffic, because the savings depend on how much repeated structure your tools return.
Does token compression change the model’s answers?
It should not, if you keep the facts the answer depends on. Headroom reports the same answers at 20% fewer tokens for coding agents and 60 to 95% fewer for JSON, and you can verify that on your own prompts by running raw and compressed context side by side. Run a regression set of real questions and check the outputs match.
How do I compress JSON ad report data before sending it to an LLM?
Fetch the report with a Creator OS ads tool such as ads:overview or ads:analytics, then pass the JSON through Headroom before you add it to the message history. Keep every field the answer needs: ad id, spend, currency, impressions and date. Let compression remove repeated campaign blocks and keys the model does not read.
How many tokens does a social media agent use per day?
It depends on how often it runs and what it reads. An agent checking comments 96 times a day with 40 comments per cycle at roughly 120 tokens each reaches about 460,000 input tokens before it writes anything, and analytics and DMs add more. Log tokens per cycle for a week to get your own number, then compress and compare.
Is Headroom a library or a proxy?
It ships as both. The library lets you compress specific payloads inside your own agent code, and the proxy lets you route model requests through it without changing client code. Use the library where you control the loop and the proxy for clients you cannot edit.
Get started with Creator OS
Creator OS gives your agent the tools to publish, reply and read analytics across 11 platforms plus Skool, all through one API key pinned to one workspace. The hosted MCP server means an agent can call list_comments, reply_to_comment or get_post_analytics with nothing to install, and Headroom compresses what those calls return. Setup steps are in the MCP docs and the CLI docs.
Creator OS plans start at $14.99/month for 11 platforms plus Skool, with the API, the MCP server and the CLI included. Start at https://www.creatoros.ca/sign-up.
Get started for $0
Free trial for new subscribers. Cancel anytime.