mcp-server

headroom: Reduce Tokens

Name: headroom: Reduce Tokens
Author: headroomlabs-ai

Get fewer tokens with same answers, powered by headroom

68,405 stars5,298 forksPythonGuide quality 8/10Updated 9/2/2026100% free · open source

What it does

Headroom reduces the number of tokens required to get the same answers from a large language model by compressing tool outputs, logs, files, and RAG chunks

When to use it

•When you need to minimize token usage for cost savings or optimization
•When your LLM workflows involve large amounts of data or logs
•When you want to improve the efficiency of your language model-powered applications

Ready-to-paste prompt

curl -X POST -H 'Content-Type: application/json' -d '["echo", "Hello World"]' http://localhost:8080/compress

Heads up: Make sure to set the `HEADROOM_URL` environment variable to the correct URL of the headroom server, otherwise the compression will not work

Saves to your device

Use with Claude

New

Skip the builder — one click puts this in Claude, Cursor, Antigravity and more.

⚡ Runs out of the box

A prompt/skill package — nothing to install beyond adding it to your AI tool.

Try it instantly — no install

Claude Code

mkdir -p ~/.claude/skills/headroomlabs-ai-headroom && curl -fsSL https://workflowstacks.com/api/skills/headroomlabs-ai-headroom/claude-skill -o ~/.claude/skills/headroomlabs-ai-headroom/SKILL.md

Open in another AI app

Opens the app with this repo with the prompt ready to go — no copy-paste needed.

Connect the whole catalog (MCP)

claude mcp add --transport http workflowstacks https://workflowstacks.com/api/mcp

Adds a WorkflowStacks connector to Claude Code: search and load any skill here by chatting.

How headroom: Reduce Tokens works

Codeflow

Free to inspect

Headroom: Reduce Tokens is a very large Python project (~274k lines across 850 code files, plus 912 test files). You install it into your AI tool with one command; there is nothing to run yourself. Last commit this month, Apache-2.0 license, has a test suite.

Size

Very large codebase

~274k lines · 850 code files · days to read — use, don't read

Setup

Install as a skill / plugin

Add it to Claude Code (or your AI tool) with one command. Nothing to run yourself.

Runs on

Inside your AI tool

Helper scripts use Python · Rust · Docker · needs API keys

Python 80%Rust 14%JavaScript 2%TypeScript 2%HTML 1%

Where to start reading

1
README.md
Start here — what it does and how to install it
2
headroom/cli.py
Where the program starts running
3
.env.example
The API keys and settings you must provide
4
headroom/__init__.py
Inside headroom/ — the main logic begins here
5
examples/07-context-compression.ipynb
A worked example — copy this to get going

What's in each folder

headroom/Core code — the actual logic534 files

plugins/Sub-packages / plugins57 files

docs/Documentation93 files

wiki/Documentation42 files

examples/Examples you can copy26 files

crates/Folder210 files

sdk/SDKs / client libraries60 files

scripts/Helper scripts37 files

READMEHas testsDocumentedCI checksDocker readyExamples includedApache-2.0 licenseUpdated this month

Use with Claude

New

Skip the builder — one click puts this in Claude, Cursor, Antigravity and more.

⚡ Runs out of the box

A prompt/skill package — nothing to install beyond adding it to your AI tool.

Try it instantly — no install

Claude Code

mkdir -p ~/.claude/skills/headroomlabs-ai-headroom && curl -fsSL https://workflowstacks.com/api/skills/headroomlabs-ai-headroom/claude-skill -o ~/.claude/skills/headroomlabs-ai-headroom/SKILL.md

Open in another AI app

Opens the app with this repo with the prompt ready to go — no copy-paste needed.

Connect the whole catalog (MCP)

claude mcp add --transport http workflowstacks https://workflowstacks.com/api/mcp

Adds a WorkflowStacks connector to Claude Code: search and load any skill here by chatting.

Quick Actions

Details

Creator

headroomlabs-ai

Language

Python