headroom

Headroom

Headroom is the transport layer: it compresses fresh tool output and new turns before they reach the model. It is not a replacement for source navigation, code review, or a model's actual context-meter.

When to use this skill

Install or update Headroom's CLI, proxy, persistent deployment, wrapper, or MCP server.
Verify whether an agent is actually routed through a healthy Headroom proxy.
Configure the code-work policy: Graphify preflight before source mutation and Ponytail minimization only once an authoritative host context percentage reaches 60.
Diagnose provider routing, proxy health, token savings, or a failed deployment.

When not to use this skill

The task is source or symbol discovery without compression concerns → use graphify or codebase-search.
The task needs a code-size reduction review without a context policy → use ponytail.
The task is generic agent configuration ownership → use agent-configuration.

Installation and persistent routing

Use the smallest upstream extra set that supports proxy, MCP, and code-aware compression. On macOS Apple Silicon and Linux, isolate it with uv:

uv tool install --python 3.13 'headroom-ai[proxy,mcp,code]'
headroom --version
headroom deploy
headroom install status
headroom doctor

headroom deploy selects a durable local runtime, configures detected supported clients, and starts the proxy on 127.0.0.1:8787. headroom install status and headroom doctor are the evidence gates. A binary on PATH alone is not proof that a client is routed through the proxy.

On Windows, install the documented MSVC and Rust prerequisites before using the Python CLI; no prebuilt Windows wheel exists at the documented release line.

Code-work policy

The optional Claude Code hook at scripts/jeo-code-policy-hook.py applies only to source-file Edit and Write operations. It uses a state directory outside the worktree and never runs graphify update itself.

On the first source mutation per session, it runs the bounded read-only preflight graphify scope <cwd> and, only for an existing graph, graphify check-update <cwd>, plus headroom doctor.
It denies that one attempt with concise retry guidance. The agent retries after using the resulting Graphify/Headroom evidence. Markdown, data, and non-source paths are untouched.
If the host hook payload explicitly includes a valid context_usage_percent >= 60, the hook denies one additional source mutation and requires the Ponytail ladder before retrying. The ladder still preserves validation, data-loss handling, security, and accessibility.
If the host does not expose that exact percentage, the hook does not infer it from transcript size, proxy savings, model names, or a presumed context window. No invented threshold is enforcement.

Install the Claude Code adapter only after the CLI and skill are present:

bash ./scripts/setup-claude-code-policy-hook.sh --dry-run
bash ./scripts/setup-claude-code-policy-hook.sh

The adapter merges one owned PreToolUse entry into ~/.claude/settings.json, backs up an existing regular file before changing it, preserves its permission mode, creates a new settings file with private 0600 permissions, and refuses symlinks or invalid JSON. It is idempotent.

Operating modes

Need	Command	Evidence
Durable automatic routing	`headroom deploy`	`headroom install status`
Health diagnosis	`headroom doctor`	reachable, configured result
One-session wrapped client	`headroom wrap claude`	wrapper launch output
On-demand MCP tools	`headroom mcp install`	client MCP listing
Manual local proxy	`headroom proxy --mode cache`	`/health` or `headroom doctor`
Code-policy preflight	hook-triggered `graphify scope` + `headroom doctor`	one retryable guard decision

Use headroom wrap <client> only for an intentional one-session path. Do not stack it on top of an already healthy persistent deployment.

Instructions

Check headroom --version and headroom doctor before changing routing.
Choose exactly one runtime path: durable deploy, a documented persistent install apply preset, or a one-session wrap. Do not start duplicate proxies.
Keep Headroom credentials and provider configuration outside the project.
For a code-work policy, install Graphify separately and use only scope and check-update in pre-mutation hooks. Run graphify update <scope> only when graph freshness is actually required because it mutates .graphify/.
Invoke Ponytail only on the authoritative context_usage_percent >= 60 signal; never estimate the percentage.
Verify the code-policy adapter with python3 scripts/jeo-code-policy-hook.py --self-test and the focused test suite before reporting it active.

Examples

Durable Claude/Codex routing

uv tool install --python 3.13 'headroom-ai[proxy,mcp,code]'
headroom deploy
headroom install status
headroom doctor

Safe context-aware minimization

A Claude Code source edit triggers the policy hook. It runs a Graphify scope preflight and Headroom diagnostic once. If the host later supplies context_usage_percent: 60, the next source edit is retried after applying the existing Ponytail ladder. It does not guess a percentage when the field is absent.

Best practices

Treat active proxy routing as a runtime property, not an install claim.
Keep automatic hooks read-only with respect to the target repository.
Cap command output and use argv lists; never interpolate hook input into shell.
Make one retryable intervention per condition, then allow the agent to proceed.
Never sacrifice trust-boundary validation, data-loss safety, security, or accessibility for shorter code.

About this skill