@casualjim/pi-headroom

Headroom context compression for pi with a working headroom_retrieve tool

Packages

Package details

extension

Install @casualjim/pi-headroom from npm and Pi will load the resources declared by the package manifest.

npm repo report
$ pi install npm:@casualjim/pi-headroom
Package
@casualjim/pi-headroom
Version
0.1.20
Published
Oct 27, 2026
Downloads
2,156/mo · 880/wk
Author
casualjim
License
MIT
Types
extension
Size
59.8 KB
Dependencies
0 dependencies · 4 peers
Pi manifest JSON
{
  "extensions": [
    "./extensions/headroom.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

@casualjim/pi-headroom

Headroom context compression for pi and omp (side by side). Compresses oversized tool results through a local Headroom proxy and exposes a headroom_retrieve tool so compressed originals stay recoverable.

Fork lineage: @raquezha/noheadroom → @ryan_nookpi/pi-extension-headroom (Jonghakseo), MIT.

Install

pi install /path/to/pi-mimir/packages/pi-headroom     # pi
omp plugin install /path/to/pi-mimir/packages/pi-headroom   # omp

Both hosts read the same source: the manifest declares pi.extensions and omp.extensions, and omp's legacy-pi compat layer remaps @earendil-works/* imports (plus typebox) onto its own packages.

Run a Headroom proxy yourself (never spawned by this package):

headroom proxy            # default port 8787
headroom proxy --port 8788   # custom port: also set baseUrl in this host's settings

The default baseUrl is http://127.0.0.1:8787 — Headroom's own default. Running a custom port (this setup uses 8788) means the settings file must set baseUrl, e.g. ~/.pi/agent/headroom/settings.json for pi and ~/.omp/agent/headroom/settings.json for omp: { "baseUrl": "http://127.0.0.1:8788" } (or export PI_HEADROOM_URL).

Settings

Resolved per host, first match wins:

Order Source
1 PI_HEADROOM_SETTINGS — exact settings file path
2 PI_CODING_AGENT_DIR → <dir>/headroom/settings.json
3 host default: ~/.omp/agent/headroom/settings.json (omp) / ~/.pi/agent/headroom/settings.json (pi)

Keys: baseUrl, enabled, mode, minContextTokens, minMessageChars, timeoutMs, allowRemote, renameToolCalls. /headroom mode <m> writes back to the file the host resolved.

Host detection is a capability probe: omp's ExtensionAPI exposes zod, pi's does not.

Retrieve

Compressed results carry a hash marker, e.g. [400 items compressed to 10. Retrieve more: hash=abc…] or <<ccr:abc…>>. Call headroom_retrieve(hash="abc…") to get the full original from the proxy's CCR store (TTL 1800 s).

/headroom status|on|off|health|stats|mode <normal|quiet|silent>

Behavior

  • Only toolResult content is mutated; user/assistant text, tool-call ids and names stay unchanged in the session.
  • Tool calls are renamed to pi_tool_result in the compression payload so Headroom's DEFAULT_EXCLUDE_TOOLS does not skip large read/grep results. Set renameToolCalls: false to keep Headroom's intended read protection.
  • Unset or unreachable proxy degrades to a no-op with a one-time warning.
  • Loop guards: reentrancy flag, 3 s throttle, input/output/candidate fingerprints, bounded seen-content FIFO.

Host compatibility

  • headroom_retrieve declares loadMode: "essential" and approval: "read". omp defaults extension tools to discoverable and exec, which would keep a marker-redeeming tool out of the top-level set and route it through the approval gate; pi ignores both fields.
  • Default timeoutMs is 20 s. The compress call runs inside the context handler, and omp kills a handler at its 30 s per-event cap (EXTENSION_HANDLER_TIMEOUT_MS), which would drop the whole context transform. pi has no such cap.
  • omp's handler context exposes no AbortSignal; a ctx.signal absence simply leaves the internal timeout as the only bound.