pi-headroom

Transparent LLM context compression for Pi using Headroom. Automatically compresses conversation context before every LLM call, saving 70–95% of tokens without changing your workflow.

Zero-config: The extension automatically installs the Headroom proxy (pip install headroom-ai[proxy]), starts it on session start, and stops it on exit. You don't need to touch the proxy manually.

How It Works

Session start → auto-install headroom-ai[proxy] → spawn proxy on :8787
                                                          ↓
User prompt → Pi builds context → pi-headroom compresses → LLM receives compressed context
                                                          ↓
Session exit → proxy stopped automatically

1. session_start: Checks if proxy is running. If not, installs headroom-ai[proxy] via pip (if needed), spawns it as a background process, and polls until healthy.
2. context event: Before every LLM call, converts Pi messages to OpenAI format, sends them to the proxy for compression, converts back, and returns compressed messages.
3. session_shutdown: Gracefully stops the proxy (only if the extension started it).

Prerequisites

• Python ≥ 3.10 — needed to run the Headroom proxy (the extension auto-installs it via pip)

That's it. The extension handles everything else.

Installation

# From local path (development)
pi install ./pi-headroom

# From npm (once published)
pi install npm:pi-headroom

# Quick test without installing
pi -e ./pi-headroom

Configuration

Env Variable	Default	Description
HEADROOM_URL	(none)	Set to use your own proxy. Disables auto-management.
HEADROOM_PORT	8787	Port for the auto-managed proxy

Auto-management vs. manual mode

• No env vars set (default): The extension auto-installs, auto-starts, and auto-stops the proxy. Zero-config.
• HEADROOM_URL set: The extension skips auto-management and health-checks the URL you provide. You manage the proxy yourself.
• HEADROOM_PORT set: The auto-managed proxy starts on your chosen port instead of 8787.

Commands

/headroom [on|off|status]

Toggle compression or show status.

• /headroom or /headroom status — Show current state, proxy mode, and session compression stats
• /headroom on — Enable compression (auto-starts proxy if needed)
• /headroom off — Disable compression (passthrough mode)

/headroom-health

Check proxy health and show diagnostics. Shows whether the proxy is managed by the extension or external.

Status Bar

The extension shows progress and compression status in Pi's footer:

• ⏳ Installing headroom-ai... — Auto-installing the proxy
• ⏳ Starting Headroom proxy... — Spawning the proxy
• ✓ Headroom — Proxy online, ready to compress
• ✓ Headroom -42% (1,234 saved) — Last compression result
• ⚠ Headroom offline — Proxy unavailable, using uncompressed context
• ○ Headroom off — Compression disabled by user

Behavior

• Zero-config: Installs and starts the proxy automatically on first use
• Smart detection: Won't reinstall or restart if already running (e.g., you started it manually)
• Graceful fallback: If anything fails, Pi continues with uncompressed context
• Crash recovery: If the proxy crashes mid-session, one automatic restart is attempted
• Clean shutdown: The proxy is stopped on session exit (only if the extension started it)
• Cross-platform: Works on macOS, Linux, and Windows

Architecture

pi-headroom/
├── package.json          # Pi package manifest
├── tsconfig.json
├── src/
│   ├── index.ts          # Extension: context hook, lifecycle, commands
│   ├── format-bridge.ts  # Pi-AI ↔ OpenAI message format conversion
│   └── proxy-manager.ts  # Auto-install, start, stop, health check
└── README.md

License

MIT