Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/headroomlabs-ai/headroom/llms.txt

Use this file to discover all available pages before exploring further.

Headroom ships a set of utility commands for diagnosing your setup, tracking savings, managing updates, and configuring persistent installations. These commands complement the main proxy, wrap, mcp, and learn commands.

​
headroom doctor

headroom doctor diagnoses whether your local Headroom setup is routing traffic and saving tokens. Because Headroom’s failure mode is silent (the client still works, you just stop saving tokens), this command correlates everything that matters: the proxy process, per-client wrap configs, the current shell environment, savings flow, and budget configuration. 
headroom doctor
Exit codes:
  • 0 — all checks pass
  • 1 — warnings only (setup works but could be improved)
  • 2 — one or more failures (traffic is not being compressed)
Checks performed:
CheckWhat it verifies
Proxy processA Headroom proxy is running and healthy
Claude Code configANTHROPIC_BASE_URL points to the proxy
Codex configbase_url in Codex config points to the proxy
Shell environmentRelevant env vars are set correctly
Savings flowTokens are actually being saved (non-zero)
Budget configBudget limit is configured if set
Proxy versionRunning proxy matches installed version
Run headroom doctor after headroom wrap to confirm routing is working.

​
headroom perf

headroom perf prints a detailed performance report showing compression latency, throughput, and per-compressor statistics for the current session. 
headroom perf
The report includes per-compressor timing (SmartCrusher, CodeCompressor, Kompress), average compression ratio, and session-level throughput in tokens per second.

​
headroom savings

headroom savings prints a cumulative savings report for all sessions recorded in the local savings ledger. 
headroom savings
headroom savings --since 7d      # last 7 days
headroom savings --format json   # machine-readable output
​
--since
string
Filter to sessions within a time window. Accepts relative values like 1d, 7d, 30d or an ISO date.
​
--format
string
default:"table"
Output format. table (default) or json.
The report shows tokens saved, estimated dollar savings (requires Python 3.13 and LiteLLM), compression ratio, and number of requests processed.
Dollar savings use LiteLLM’s pricing database, which requires Python 3.13 or earlier. On Python 3.14+, the dollar figure shows $0.00 while token savings still track correctly.

​
headroom output-savings

headroom output-savings estimates how many output tokens were saved by verbosity steering and effort routing. Because output savings are counterfactual (we never see what the model would have written), this command reports an honest estimate with a confidence interval rather than a single number. 
headroom output-savings
# Reduction: 31.7%  (95% CI 27.7% … 35.7%)   [estimated]
If you’ve set HEADROOM_OUTPUT_HOLDOUT=0.1 to run a control group, the result is labeled measured instead of estimated: 
export HEADROOM_OUTPUT_HOLDOUT=0.1
headroom proxy --port 8787
# ... after some usage ...
headroom output-savings
# Reduction: 28.4%  (95% CI 24.1% … 32.7%)   [measured, n=42 control]
See Output Token Reduction for full details.

​
headroom dashboard

headroom dashboard opens the live savings dashboard in your browser. The proxy must be running. 
headroom dashboard
headroom dashboard --port 8080   # if running on a non-default port
​
--port
integer
default:"8787"
Port the proxy is running on.
​
--no-open
flag
Print the dashboard URL instead of opening a browser window. Useful in headless or SSH environments.
The dashboard shows:
  • Input tokens saved (live, per request)
  • Output tokens saved (if HEADROOM_OUTPUT_SHAPER=1)
  • Compression ratio over time
  • Per-agent savings breakdown
  • Dollar savings (labeled measured or estimated)
The same data is available as a browser dashboard at http://localhost:8787/dashboard when the proxy is running.

​
headroom update

headroom update detects how Headroom was installed (pip, pipx, or uv tool) and upgrades in place. 
headroom update            # upgrade to latest stable
headroom update --check    # print latest version, don't upgrade
headroom update --pre      # include pre-release versions
​
--check
boolean
Report the latest available version without performing the upgrade.
​
--pre
boolean
Include pre-release versions when checking or upgrading.
For git checkouts, editable installs, Docker images, and externally-managed system Pythons (PEP 668), headroom update prints the correct manual step instead of guessing. The proxy shows a one-line “update available” notice on startup (at most once per day, non-blocking). Opt out with HEADROOM_UPDATE_CHECK=off.

​
headroom init / headroom install apply

headroom init generates a persistent service configuration (systemd unit, launchd plist, or Windows Service) for running the proxy as a background service. 
headroom init                   # generate config for current platform
headroom init --port 8787       # custom port
headroom install apply          # install and start the generated service
headroom install status         # check service status
headroom install stop           # stop the service
headroom install remove         # uninstall the service
​
--port
integer
default:"8787"
Port for the persistent proxy service.

​
headroom copilot-auth

headroom copilot-auth manages a Headroom-specific GitHub OAuth token for GitHub Copilot CLI subscription mode. 
headroom copilot-auth login    # authenticate with GitHub
headroom copilot-auth logout   # remove stored token
headroom copilot-auth status   # show token validity
The stored token is separate from the generic GitHub or Copilot CLI tokens. It is used by headroom wrap copilot --subscription to exchange for Copilot’s short-lived API token and locate the upstream endpoint. See Agent Wrap for the full Copilot subscription setup flow.

​
headroom agent-savings

headroom agent-savings prints a savings breakdown by agent (Claude Code, Codex, Cursor, etc.) for the current session ledger. 
headroom agent-savings
headroom agent-savings --format json

​
headroom capture

headroom capture manually records a session or set of messages into the savings ledger without routing through the proxy. Useful for auditing or testing. 
headroom capture --file messages.json
​
--file
string
required
Path to a JSON file containing the messages array to record.

Build docs developers (and LLMs) love

Get started for freeTalk to us