headroom

Headroom

Headroom saves context window by compressing large tool outputs and retrieving originals later.

Upstream: https://github.com/headroomlabs-ai/headroom

Resolve

MCP tools present in session (headroom_compress, headroom_retrieve, …) → use them
Else CLI: headroom --help / $env:HEADROOM_CMD
Else recommend install

Install recommendation

pip install "headroom-ai[mcp]"     # tools only
pip install "headroom-ai[proxy]"   # proxy + tools
headroom mcp install               # where supported (e.g. Claude Code)

When to use

Huge logs, greps, JSON dumps, crash stacks before reasoning
Need original later → keep the returned hash and headroom_retrieve

When not to use

Tiny snippets
Replacing Skyrim domain skills
Fabricating compression when MCP is down — just summarize carefully instead

Multi-provider

Works with any MCP host (Claude, Cursor, Codex, Grok, …) once the server is registered. If registration fails, say so and continue without Headroom.

Grok: MCP only. Never wrap Grok inference.

Do not run headroom wrap grok, and do not set GROK_MODELS_BASE_URL, unless the user has an XAI_API_KEY.

Headroom's Grok proxy forwards to https://api.x.ai and authenticates with XAI_API_KEY (headroom/providers/grok/runtime.py → DEFAULT_API_URL; headroom/cli/wrap.py → openai_api_url="https://api.x.ai").

A Grok subscription / OIDC login (~/.grok/auth.json with auth_mode=oidc) does not use api.x.ai at all — its endpoint is https://cli-chat-proxy.grok.com/v1. Headroom has no code path for it, so wrapping such an account produces:

model catalog: all retries exhausted  ("model catalog fetch returned no models")
  -> the model selector shows "unknown"; grok-4.5 becomes unselectable
Unauthorized (401) from http://127.0.0.1:8787/p/<project>/v1/chat/completions
  -> every turn fails

This is an auth-shape mismatch, not a misconfiguration. There is no flag that makes the wrap work for a session login.

Decide by auth mode

`~/.grok/auth.json`	`XAI_API_KEY`	What Headroom may do
`auth_mode=oidc` (subscription)	absent	MCP tools only
any	present	MCP tools + optional inference wrap

Correct Grok setup

.\TOOLS\Ensure-Headroom-Grok.ps1            # MCP registration, auth aware (default)
.\TOOLS\Ensure-Headroom-Grok.ps1 -CheckOnly # report, change nothing
.\TOOLS\Ensure-Headroom-Grok.ps1 -Repair    # undo a v5.0 wrap that broke Grok
.\TOOLS\Ensure-Headroom-Grok.ps1 -Wrap      # opt in; refuses without XAI_API_KEY

[mcp_servers.headroom] in ~/.grok/config.toml gives Grok headroom_compress / headroom_retrieve / headroom_stats. That is on-demand compression the agent calls deliberately — it is not automatic traffic compression, and for a subscription account it is the only mode available. Say that plainly rather than promising auto-compress.

Symptom → cause

If a user reports Grok showing an "unknown" model, or losing access to grok-4.5, check in this order:

GROK_MODELS_BASE_URL / GROK_MODEL_GROK_BUILD_BASE_URL set to 127.0.0.1 → wrap is active, remove it
A function grok in the PowerShell profile calling headroom wrap grok → rename/remove it
~/.headroom/deploy/default/manifest.json with grok / grok_build in targets → headroom install remove --profile default (the deploy re-applies those env vars on every health check)
~/.grok/models_cache.json with origin pointing at 127.0.0.1 → delete it so Grok refetches the real catalog

Then start a new shell and run grok.

Verify

headroom install status
# For a subscription account the correct state is:
#   no GROK_* base-url env vars
#   no grok/grok_build deploy targets
#   [mcp_servers.headroom] present in ~/.grok/config.toml
#   ~/.grok/models_cache.json origin = https://cli-chat-proxy.grok.com/v1/models