pi-hypa

Pi extension package for Hypa. 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 bundled dependency.

The current package provides:

• bash rewrite interception via hypa rewrite --json
• /hypa diagnostics
• CLI-backed tools: hypa_shell, hypa_read, hypa_grep, hypa_find, hypa_ls
• optional Hypa MCP proxy discovery tool: hypa_mcp_proxy

Bash interception mutates the Pi bash command before execution when Hypa returns Rewritten or GenericWrapper.

Install / smoke

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

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 Pi bash/read/grep/find/ls after registering hypa_* tools.
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.

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 deterministic non-UI fallback.
• hypa_* tool outputs are capped at 50KB / 2000 lines; truncated full output is saved to a temp file.