headroom_plus_rtk.md

headroom_plus_rtk.md

Quickstart: headroom + rtk together

Context

The user wants a straightforward quickstart to run headroom (this repo — headroom-ai, a context-compression HTTP proxy that sits in front of an LLM API and shrinks tool outputs/history/RAG chunks before they hit the model) alongside their globally-installed rtk ("Rust Token Killer", Homebrew binary at /opt/homebrew/bin/rtk, wired into Claude Code via a PreToolUse hook in ~/.claude/settings.json that rewrites Bash commands like git status → rtk git status to shrink their stdout before it enters context).

Important discovery: headroom ships its own, unrelated internal component also named "rtk" — "Realtime Token Kompress" (docs/rtk-architecture.md) — a shell-command rewriter that only runs inside headroom wrap <agent> mode. Its _ensure_rtk_binary() installs a ~/.rtk/bin/rtk shim ahead of the agent CLI on PATH. If the user runs headroom wrap claude without care, headroom's own rtk shim will shadow their real Homebrew rtk binary, breaking the existing rtk hook claude PreToolUse integration (which expects the real rtk's CLI surface, not headroom's differently-behaved internal one).

The two tools are complementary, not redundant: rtk operates on shelled-out command output (pre-context, local); headroom's proxy operates on the full request payload sent to the LLM API (network layer). Running headroom in plain proxy mode (not wrap mode) avoids the naming collision entirely and lets both run simultaneously with zero interference.

Recommended approach: headroom proxy + existing rtk hook (no wrap)

Avoid headroom wrap claude for this setup — it's unnecessary here (its main benefit, injected agent instructions + unified RTK metrics dashboard, isn't needed for a simple quickstart) and it's the one path that risks clobbering the user's real rtk on PATH.

Steps

1. Install headroom (Python CLI via uv, per wiki/getting-started.md):

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

   (Use uv tool update-shell if headroom isn't found on PATH after install.)

2. Confirm rtk is untouched — nothing to configure; the existing ~/.claude/settings.json PreToolUse hook (rtk hook claude) and ~/Library/Application Support/rtk/config.toml keep working exactly as they do today. This step is just a verification, not a change:

   rtk --version
   rtk gain

3. Start the headroom proxy (default port 8787), in its own terminal or background process:

   headroom proxy --port 8787

4. Point Claude Code at the proxy via env var, then launch normally:

   ANTHROPIC_BASE_URL=http://localhost:8787 claude

   Now every request Claude Code sends flows through headroom's compression pipeline before reaching Anthropic, while rtk continues independently shrinking Bash tool-call output via its existing hook.

5. Verify both are contributing savings:

   • rtk: rtk gain / rtk gain --history
   • headroom: open the dashboard at http://localhost:8787/dashboard (or headroom perf) to see proxy-side compression stats.

If the user later wants headroom wrap claude instead

Only do this if they specifically want headroom's wrap-mode extras (auto-injected agent instructions, unified wrap_rtk_* metrics). In that case, pass --no-rtk explicitly to stop headroom from installing/using its own internal rtk shim, so it doesn't compete with the real Homebrew rtk already hooked into Claude Code:

headroom wrap claude --no-rtk

Without --no-rtk, headroom's wrap CLI will attempt to install its own ~/.rtk/bin/rtk ahead of PATH — do not combine plain headroom wrap claude (no flag) with the existing rtk hook setup.

Verification

• headroom --version and rtk --version both resolve correctly.
• With the proxy running and ANTHROPIC_BASE_URL set, start a Claude Code session, run a few Bash tool calls (e.g. git log, git status) and confirm:
  • rtk gain shows non-zero savings (rtk hook still active).
  • http://localhost:8787/dashboard (or headroom perf) shows non-zero compressed requests (proxy active).
• No PATH/shim conflicts: which rtk still resolves to /opt/homebrew/bin/rtk after the session (only relevant if headroom wrap was ever tried without --no-rtk).