How to use Headroom to compress the tool output and logs Claude Code reads and save tokens

Headroom is an open-source tool that compresses tool outputs, logs, files and conversation history on your machine before they reach the model. It sits in front of Claude Code or Codex as a local proxy and keeps the originals locally, so the model can pull them back with headroom_retrieve when it needs them. Version 0.41.0 shipped on October 13, and the repo has passed 75,000 GitHub stars.

1. Install the CLI. The headroom command ships only in the PyPI package; the npm headroom-ai package is a TypeScript library with no command.

uv tool install --python 3.13 "headroom-ai[all]"

1. Launch Claude Code wrapped by Headroom. This starts the local proxy, registers the Serena MCP server for code navigation in the current project only, and then opens Claude Code. Launch each session this way so the setup applies. For Codex, use headroom wrap codex.

headroom wrap claude

Add --code-memory-scope user to make Serena available in every project, or --code-memory none to skip it.

1. Check that routing works and see how much you saved. The dashboard only opens while the proxy is running.

headroom doctor
headroom dashboard

1. To undo, use unwrap. It removes the Serena registration too.

headroom unwrap claude

An anonymous telemetry beacon is on by default. It says it never sends prompts, code or file paths; to turn it off, set the environment variable HEADROOM_TELEMETRY=off.