pi-headroom

Headroom proxy extension for pi-coding-agent. Routes requests through a local Headroom compression proxy for 30-60% token savings.

Features

• Proxy routing — Redirects opencode-go provider traffic through local Headroom proxy
• CCR retrieval — Registers headroom_retrieve tool for cache-compress-retrieve support
• Auto-detection — Checks if proxy is running, falls back to direct connection
• Configurable — Port, host, and feature flags via config file

Installation

Prerequisites

1. Install pi-coding-agent
2. Install uv (for running headroom)

Install pi-headroom

# Option 1: Install via pi (recommended)
pi install npm:@rsrini/pi-headroom

# Option 2: Add to ~/.pi/agent/settings.json
{
  "packages": ["npm:@rsrini/pi-headroom"]
}

Quick Start

Option A: Use the hpi wrapper script (recommended)

The easiest way to use both plugins together:

# Download the hpi script
curl -O https://raw.githubusercontent.com/rsrini7/pi-headroom/main/hpi.sh
chmod +x hpi.sh

# Add to your shell
echo 'source /path/to/hpi.sh' >> ~/.zshrc
source ~/.zshrc

# Start pi with both extensions
hpi

Option B: Manual setup

# 1. Start Headroom proxy
uvx --python 3.12 --from 'headroom-ai[proxy,ml,code]==0.27.0' \
  headroom proxy --port 8787 --memory --code-aware

# 2. In another terminal, start pi with the extension
pi -e npm:@rsrini/pi-headroom

Option C: Configure in settings.json

# Install both plugins
pi install npm:@rsrini/pi-rtk
pi install npm:@rsrini/pi-headroom

# They're now active for all pi sessions
pi

Token Reduction Stack

Tool output  →  pi-rtk (60-90%)  →  Pi context  →  Headroom (30-60%)  →  LLM
                  ↑ client-side                        ↑ proxy-side

| Layer | What | Where | Savings | |-------|------|-------|---------| | pi-rtk | Filters tool output (bash, read, grep) | Pi client | 60-90% | | pi-headroom | Routes through compression proxy | Pi client | 30-60% | | Headroom | Compresses full context window | Proxy :8787 | 30-60% |

Combined savings: 70-95% depending on content type.

Configuration

Create ~/.pi/agent/headroom-config.json:

{
  "enabled": true,
  "proxy": {
    "host": "localhost",
    "port": 8787
  },
  "features": {
    "compression": true,
    "caching": true,
    "retrieval": true
  }
}

Commands

| Command | Description | |---------|-------------| | /headroom-stats | Show compression statistics | | /headroom-on | Enable proxy routing | | /headroom-off | Disable proxy routing | | /headroom-status | Check proxy connection status |

Agent Tool

The headroom_retrieve tool allows the AI agent to retrieve cached context when needed.

The hpi Wrapper Script

The hpi script provides a seamless experience:

# Start with both plugins (local dev mode)
hpi

# Use npm published packages
hpi --npm

# Use specific model
hpi --npm --model openrouter/claude-sonnet-4

# One-shot mode
hpi --npm -p "fix the bug"

# Stop the proxy
hpi --stop

Flags

| Flag | Description | |------|-------------| | --npm | Use npm published packages | | --local | Use local workspace paths (default) | | --no-rtk | Skip rtk extension (headroom only) | | --stop | Kill the headroom proxy | | --model | Override model | | --thinking | Override thinking level |

Combining with pi-rtk

For maximum savings, install both:

pi install npm:@rsrini/pi-rtk
pi install npm:@rsrini/pi-headroom

Or use the hpi wrapper which handles both automatically.

Troubleshooting

Proxy not starting

# Check if port is in use
lsof -i :8787

# Kill existing processes
hpi --stop

# Check logs
cat ~/.pi/agent/headroom.log

Extension not loading

# Verify installation
pi list

# Check settings
cat ~/.pi/agent/settings.json

# Test with verbose output
pi -e npm:@rsrini/pi-headroom --verbose

License

MIT