# Headroom Setup Guide for Claude

Headroom is an open-source context compressor that sits between you and Claude. It strips redundant tokens from logs, files, and database dumps before they reach the model — same answers, 60–90% fewer tokens.

- GitHub: https://github.com/headroomlabs-ai/headroom
- Docs: https://headroom-docs.vercel.app

## What you need

- Python 3.9 or newer
- `pip` installed and working
- Claude Code already installed (`claude` command works in your terminal)

## Install Headroom

```bash
pip install "headroom-ai[all]"
```

The `[all]` extra installs the CLI plus the default set of compressors.

## Wrap Claude

```bash
headroom wrap claude
```

This creates a `headroom`-wrapped version of the Claude CLI. When you run it, every prompt is compressed before it is sent to Anthropic.

## Use Claude normally

```bash
claude
```

From this point on, Headroom runs in the background. Paste logs, ask questions, run agents — everything works the same way, but with fewer input tokens.

## Check your savings

```bash
headroom dashboard
```

The dashboard shows how many tokens were removed and how much context was preserved.

## Common use cases

- Large stack traces and repeated log lines
- Database dumps and verbose schemas
- Multi-file diffs with unchanged hunks
- Long error messages copied from a terminal

## Need help?

If Claude Code is not on your PATH, or you use a virtual environment, run `headroom wrap claude --help` to see the full set of options. For the latest install notes, see the official docs at https://headroom-docs.vercel.app.