pi-hypa

The Pi extension for Hypa — a local context runtime for coding agents.

@hypabolic/pi-hypa wires Hypa into the Pi coding agent. Hypa reduces the noisy tool output that reaches an agent's context window: it runs locally, compresses shell output with deterministic reducers, exposes context-aware file and code tools, and records enough evidence to recover the details that matter.

Pi bash / tool call
        ↓
      Hypa
        ↓
errors · warnings · changed files · failing tests · exit codes

Hypa is not an LLM summarizer. The default reduction path is local, deterministic, and testable — your source code and command output do not need to be sent to a separate cloud service.

What this extension adds

Installing this package through Pi also installs @hypabolic/hypa as a package dependency and creates a best-effort user-level hypa shim when no hypa command is already on PATH. The shim delegates to a later global/system hypa install if one appears earlier on PATH, and otherwise falls back to the platform-native binary from optional deps (or bin.js via the install-time JS runtime when the native package is unavailable).

The extension provides:

• Bash rewrite interception via hypa rewrite --json — Pi's bash command is mutated before execution when Hypa returns Rewritten or GenericWrapper, so command output is compressed in place.
• /hypa diagnostics — inspect extension mode, binary resolution, MCP proxy setting, and the last rewrite status.
• CLI-backed tools — hypa_shell, hypa_read, hypa_grep, hypa_find, hypa_ls.
• Optional Hypa MCP proxy — the hypa_mcp_proxy discovery tool for upstream MCP servers.

Install

This extension is installed automatically when you run hypa init --agent pi (or hypa init with Pi detected). To install or test it directly:

pi -e ./packages/pi-hypa/extensions/index.ts
# or
pi install ./packages/pi-hypa
# from npm
pi install npm:@hypabolic/pi-hypa

Requirements

• Pi with the @earendil-works/pi-coding-agent peer dependency.
• Node.js 18 or newer, or Bun (Pi with "npmCommand": ["bun"] works without Node on PATH).
• Linux, macOS, or Windows on x64 or arm64 (the bundled @hypabolic/hypa selects the matching native binary).

Hypa is invoked via the platform-native binary whenever it is installed as an optional dependency. Node is not required at runtime for the extension when that native binary is available. If only the bin.js launcher is present, the extension runs it with the host JS runtime (process.execPath — bun under Bun, node under Node) instead of hardcoding node.

Configuration

| Variable | Default | Description | |---|---|---| | HYPA_BIN | bundled @hypabolic/hypa, then hypa | Hypa executable or absolute path. | | HYPA_PI_MODE | additive | additive keeps Pi builtins; replace disables each of Pi bash/read/grep/find/ls only while its matching hypa_* tool is active (fail-open if the replacement is absent, e.g. subagent/--tools allowlists). | | HYPA_PI_REWRITE_TIMEOUT_MS | 5000 | Rewrite CLI timeout in milliseconds. | | HYPA_PI_ASK_NON_INTERACTIVE | deny | Ask fallback when ctx.hasUI === false: deny or allow. | | HYPA_PI_ENABLE_MCP_PROXY | 0 | Enable hypa_mcp_proxy, a lazy discovery/invocation bridge for upstream MCP servers configured in Hypa. | | HYPA_PI_ENABLE_MCP | unset | Legacy alias for HYPA_PI_ENABLE_MCP_PROXY if needed. | | HYPA_PI_MCP_PROXY_TIMEOUT_MS | 10000 | Timeout for hypa mcp ... proxy calls. | | HYPA_PI_MCP_CONFIG | ~/.pi/agent/mcp.json | Pi MCP config path used to deduplicate Hypa upstream servers already configured directly in Pi. | | HYPA_PI_CONFIG | ~/.hypa-pi/config.json | JSON config file path. Set to none or an empty string to skip file loading. |

Environment variables override config file values, and config file values override built-in defaults. The JSON file uses camelCase field names:

{
  "mode": "additive",
  "binary": "hypa",
  "rewriteTimeoutMs": 5000,
  "askNonInteractive": "deny",
  "mcpProxyEnabled": false,
  "mcpProxyTimeoutMs": 10000,
  "piMcpConfigPath": "~/.pi/agent/mcp.json"
}

All JSON fields are optional.

CLI-backed tools

When registered, the extension exposes Hypa-backed equivalents of Pi's file and shell builtins. In additive mode they sit alongside Pi's own tools; in replace mode each hypa_* tool takes over its matching builtin only when both are active.

| Tool | Replaces | Purpose | |---|---|---| | hypa_shell | bash | Run shell commands with rewrite rules, compression, and evidence recording. | | hypa_read | read | Read files with full, outline, signatures, pruned, or smart selection. | | hypa_grep | grep | Search file contents with safe ripgrep options. | | hypa_find | find | Find files with an optional result limit. | | hypa_ls | ls | List directory contents. |

hypa_* tool outputs are capped at 50KB / 2000 lines; truncated full output is saved to a temp file for recovery.

MCP proxy discovery

When HYPA_PI_ENABLE_MCP_PROXY=1, the extension registers one compact tool, hypa_mcp_proxy, instead of dumping every upstream MCP server/tool into Pi context.

Supported actions:

• list — compact list of upstream MCP servers configured in Hypa
• search — search upstream tools by query
• schema — fetch details/schema on demand for a selected server
• invoke — invoke a selected upstream tool through Hypa's proxy/passthrough service
• auth_check — validate auth for a selected upstream server

Servers already configured directly in Pi are filtered by default. Pass includeDuplicates=true to inspect/invoke through Hypa anyway.

Diagnostics

Run /hypa in Pi to show extension mode, binary resolution, MCP proxy setting, and the last rewrite status/error.

Safety

• Commands already starting with hypa are not rewritten.
• Parse, timeout, or process errors fail open by passing the original command through and recording diagnostics.
• Deny blocks the tool call.
• Ask confirms in UI mode and uses a deterministic non-UI fallback.
• hypa_* tool outputs are capped at 50KB / 2000 lines; truncated full output is saved to a temp file.

Documentation

• Pi integration guide
• Hypa documentation
• GitHub repository
• @hypabolic/hypa on npm
• Issue tracker

License

Hypa is licensed under the Functional Source License 1.1 with an Apache License 2.0 future license.