@ryan_nookpi/pi-extension-headroom

This extension reclaims context window in pi by compressing large tool results through a Headroom proxy before each LLM call.

Headroom runs locally, compresses only oversized toolResult payloads, and leaves your prompts, assistant turns, and tool-call metadata untouched. Compression is applied only when the proxy is online and the change passes strict alignment guards, so it never silently rewrites your conversation.

Install

pi install npm:@ryan_nookpi/pi-extension-headroom

You also need the Headroom proxy available on your machine:

pip install "headroom-ai[proxy]"

By default the extension auto-starts a local token-mode proxy (headroom proxy --mode token --no-cache) on http://127.0.0.1:8788 and leaves it running after pi exits.

How it works

• Listens on the context event fired before each LLM call.
• Skips entirely until context usage reaches the configured token threshold.
• Sends an OpenAI-shaped copy of the conversation to the proxy's /v1/compress endpoint.
• Applies the result only to large toolResult messages, preserving pi metadata (toolName, details, tool-call ids, images).
• Rejects any response that changes message count, roles, tool-call ids, or non-candidate content.

Privacy

Compression sends conversation context to the proxy, so remote URLs are blocked by default. Only localhost/127.0.0.1/::1 are allowed unless you explicitly set PI_HEADROOM_ALLOW_REMOTE=1 for a proxy you trust.

Commands

• /headroom — show current status and session stats.
• /headroom on — enable compression and ensure the proxy is running.
• /headroom off — disable compression for this session (the proxy keeps running).
• /headroom health — check / start the proxy and report whether it is online.
• /headroom stats — print the proxy's own /stats output.
• /headroom-health — shortcut for /headroom health.

The footer shows a compact status (✓ Headroom -42% (12,345 saved)) once compression is applied.

Configuration

Settings are read at startup from ~/.pi/agent/headroom/settings.json. Values in this file override environment variables; environment variables remain supported as fallbacks.

Example:

{
  "minContextTokens": 10000,
  "minMessageChars": 1000
}

| Setting key | Env fallback | Default | Description | | --- | --- | --- | --- | | enabled | PI_HEADROOM_ENABLED | true | Enable compression on start. | | baseUrl (url also accepted) | PI_HEADROOM_URL (HEADROOM_URL / HEADROOM_BASE_URL also accepted) | http://127.0.0.1:8788 | Proxy base URL. | | allowRemote | PI_HEADROOM_ALLOW_REMOTE | false | Allow non-local proxy URLs. | | autoStart | PI_HEADROOM_AUTO_START | true | Auto-start a local persistent proxy when offline. | | command | PI_HEADROOM_COMMAND | headroom | Command used to launch the proxy. | | minContextTokens | PI_HEADROOM_MIN_CONTEXT_TOKENS | 20000 | Skip compression below this context token count. | | minMessageChars | PI_HEADROOM_MIN_MESSAGE_CHARS | 2000 | Only compress tool results at or above this size. | | timeoutMs | PI_HEADROOM_TIMEOUT_MS | 30000 | HTTP timeout for proxy requests. |

Boolean values accept JSON booleans, or strings such as 1/0, true/false, yes/no, on/off.