pi-hofund

Bifrost AI Gateway control-plane extension for Pi (models, MCP, skills, prompts)

Packages

Package details

extension

Install pi-hofund from npm and Pi will load the resources declared by the package manifest.

$ pi install npm:pi-hofund
Package
pi-hofund
Version
0.2.2
Published
Nov 8, 2026
Downloads
970/mo · 552/wk
Author
flynnham
License
MPL-2.0
Types
extension
Size
131.6 KB
Dependencies
0 dependencies · 3 peers
Pi manifest JSON
{
  "extensions": [
    "./index.ts"
  ]
}

Security note

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

README

pi-hofund is an extension for the Pi coding agent that connects directly to a self-hosted Bifrost AI Gateway.

Instead of treating Bifrost as just an OpenAI-compatible URL, pi-hofund exposes the gateway's control plane to Pi: dynamic model catalogs, Virtual MCP tool servers, managed skills, and prompt repositories are integrated into Pi as native surfaces, scoped to your Bifrost Virtual Key.

Why pi-hofund?

Pointing Pi at an OpenAI-compatible proxy URL only provides raw chat completions. You still have to transcribe model IDs by hand, guess context limits and pricing, configure MCP servers individually, and manually distribute skills and prompt templates.

pi-hofund turns Bifrost into the single source of truth for your Pi environment:

Surface Generic OpenAI Base URL With pi-hofund
Models Transcribe model IDs manually; guess limits, pricing, and reasoning parameters Auto-registered bifrost provider derived live from Bifrost's /v1/models catalog
Tools (MCP) Manually maintain tool configs in mcp.json Dynamic tool discovery: registers one MCP server per Virtual MCP slug, with a whole-key fallback
Skills Manually copy and sync SKILL.md folders across machines Opt-in, atomic sync of Bifrost's public skills bundles into ~/.pi/agent/skills/
Prompts Manually maintain prompt templates Opt-in sync of versioned prompt repositories into ~/.pi/agent/prompts/bifrost/
Freshness Static until configuration files are edited TTL-checked, coalesced background refresh, re-synced on session start or on demand
Governance Treated as an unmetered, generic client Gateway budgets, rate limits, team scopes, and audit logs remain strictly enforced

Core Design Principles

  • Derived, never guessed: Every model attribute (reasoning capabilities, context windows, pricing, thinking levels) is derived directly from Bifrost's own catalog. There are no fallback catalogs, magnitude guesses, or arbitrary compat flags. A provider whose aggregate entry is a bare stub is completed from the upstream metadata Bifrost echoes on its provider-scoped listing; a value Bifrost reports nowhere keeps a documented conservative default.
  • Scoped & governed: All inference and tool calls pass through your Bifrost Virtual Key (VK). Prompts require an optional management key; skills sync from public bundles. Pi only accesses what your key is permitted to see.
  • Safe & non-destructive: Synced assets carry a managed-by: pi-hofund front-matter marker. Existing local skills and custom prompts without this marker are never overwritten or removed.
  • Zero runtime dependencies: Built entirely on Node.js built-ins (node:zlib for archive handling) and Pi extension APIs.

Prerequisites

  • Node.js >= 22
  • Pi coding agent (@earendil-works/pi-coding-agent)
  • A running Bifrost instance with a valid Virtual Key (and an optional Management Key if prompt repository sync is enabled)

Quickstart

1. Install the extension

Install pi-hofund as a persistent Pi package:

pi install npm:pi-hofund

(To test the extension for a single run without installing, use pi -e npm:pi-hofund.)

2. Connect to Bifrost

Launch Pi and run the login command:

/login bifrost

Pi will prompt you for:

  1. Bifrost URL — the mount URL of your gateway (e.g. https://bifrost.example.com/openai/v1).
  2. Virtual Key — your Bifrost virtual key.

Credentials are saved securely in Pi's credential store (~/.pi/agent/auth.json). The login flow writes the resolved shape itself — { type: "api_key", key: "pi-hofund-keyless", env: { BIFROST_URL, BIFROST_VIRTUAL_KEY } } — so the extension always finds the gateway URL and virtual key it needs, and re-running /login bifrost repairs any legacy bare-key entry. The virtual key is never written to settings.json and is never read from global environment variables.

3. Start using models

Models from your Bifrost gateway are available immediately under the bifrost/ provider prefix:

/model bifrost/<model-id>

To set Bifrost as your default provider, add "defaultProvider": "bifrost" in ~/.pi/agent/settings.json.

4. Enable optional surfaces

Run the interactive settings menu to enable MCP, skills, or prompt syncing:

/bifrost:settings

Toggle desired features with Space, save with Ctrl+S, or reload the catalog on demand using /bifrost:reload.

Surfaces & Features

Dynamic Model Catalog (bifrost/*)

The bifrost provider registers all models exposed by your Virtual Key via Bifrost's /v1/models catalog:

  • Context limits, max tokens, pricing, and reasoning flags are populated directly from gateway metadata. Model ids are Bifrost's own routable, provider-prefixed ids.
  • Providers that omit limits, prices, or capabilities from the aggregate listing (for example opencode-go) are completed from the upstream metadata Bifrost echoes on GET /v1/models?provider=<provider>; an entry that already declares its own limits is never rewritten.
  • Catalog updates are cached with a configurable TTL (default 6 hours) and refreshed automatically on session start.
  • Concurrent refreshes are coalesced into a single aggregate catalog request, plus one provider-scoped echo per provider that reports no limits.
  • Run /bifrost:reload at any time to bypass the cache and force an immediate refresh.

Per-Upstream Request Hooks

Each src/providers/<upstream>.ts file is auto-discovered and may adjust the outgoing headers, the outgoing chat-completions body, and each incoming stream event for models whose id starts with that upstream:

  • The shipped opencode-go override attaches x-bf-eh-x-opencode-session: <pi session id>, which Bifrost forwards so an opencode session stays pinned to one backend. Nothing else is rewritten.
  • Hooks run in-process, perform no network I/O, and a throwing hook is reported and bypassed.

Virtual MCP Tool Servers

When hofund.features.mcp is enabled:

  • pi-hofund queries Bifrost for Virtual MCP configurations assigned to your Virtual Key.
  • Virtual MCP slugs register as native Pi MCP servers via pi.registerMcpServer.
  • If no virtual slugs exist, a whole-key fallback server (mcp__hofund) is registered so all key-accessible tools remain available.
  • All MCP servers unregister cleanly on session shutdown.

Managed Skills Sync

When hofund.features.skills is enabled:

  • Pi downloads the public skills archive from Bifrost and materializes them as flat skill directories inside ~/.pi/agent/skills/.
  • Safety guarantee: Synced skills are tagged with managed-by: pi-hofund in their SKILL.md front-matter. Unmanaged user skills are preserved and never modified or deleted during sync or cleanup.
  • Use hofund.zipPathPrefix (e.g. "pi/") to limit synchronization to a subfolder within the upstream archive.

Prompt Repositories

When hofund.features.prompts is enabled (requires a management key):

  • Synchronizes versioned prompts from Bifrost's prompt repository into ~/.pi/agent/prompts/bifrost/.
  • Bifrost's ordered message arrays and parameter specifications are projected into Pi's markdown template structure.
  • As with skills, prompts are tracked via manifests and local unmanaged templates are preserved.

Interactive Commands

Command Purpose
/login bifrost Interactively prompt for gateway URL and Virtual Key, then write the resolved credential (URL + key in env) to auth.json.
/bifrost:settings Open the interactive TUI settings screen to toggle MCP, skills, and prompts, or view current config.
/bifrost:reload Force an immediate catalog refresh and re-run active surface syncs.

Configuration Reference

Settings can be managed interactively with /bifrost:settings or edited directly in ~/.pi/agent/settings.json under the hofund key:

{
	"hofund": {
		"url": "https://bifrost.example.com/openai/v1",
		"features": {
			"mcp": true,
			"skills": true,
			"prompts": false
		},
		"modelTtlMinutes": 360,
		"zipPathPrefix": "pi"
	}
}

Options

Setting Type Default Description
hofund.url string required Base URL of your Bifrost OpenAI-compatible endpoint (e.g. https://bifrost.example.com/openai/v1).
hofund.features.mcp boolean false Discover and register Virtual MCP tool servers.
hofund.features.skills boolean false Synchronize Bifrost public skills into ~/.pi/agent/skills/.
hofund.features.prompts boolean false Synchronize prompt repository into ~/.pi/agent/prompts/bifrost/ (requires management key).
hofund.modelTtlMinutes number 360 Catalog refresh cache duration in minutes.
hofund.zipPathPrefix string undefined Restrict skills sync to a specific subfolder inside the skills ZIP bundle.
hofund.apiKey string undefined Optional upstream API authentication key.
hofund.managementKey string undefined Management API key for prompt sync (prefer setting HOFUND_MANAGEMENT_KEY in environment).

Environment Variables & CLI Flags

For headless environments, Docker containers, or scripted setups, configuration resolves using the following precedence:

  1. CLI Flags: --hofund-url, --hofund-api-key, --hofund-virtual-key
  2. Environment Variables:
    • BIFROST_URL — Gateway base URL.
    • BIFROST_API_KEY — Optional upstream API key.
    • HOFUND_MANAGEMENT_KEY — Management API key (used for prompt repository access).
  3. Settings File: ~/.pi/agent/settings.json (hofund.* block).
  4. Credential Store: ~/.pi/agent/auth.json (populated via /login bifrost).

Note on security: The Virtual Key is read from auth.json or the explicit --hofund-virtual-key flag. It is never read from ambient environment variables to avoid accidental exposure in process listings or logs.

Advanced: Upstream Traffic Overrides

If a specific model provider routed behind Bifrost requires payload adjustments or custom stream handling, pi-hofund supports file-discovered overrides:

  • Drop a module at src/providers/<upstream>.ts (where <upstream> matches the first segment of the model ID, e.g. opencode-go).
  • Export processOutgoing(body, meta) to modify outgoing JSON request payloads.
  • Export processIncoming(event, meta) to transform streamed assistant message events.
  • See docs/extending.md for details and conventions.

Behind the Name

In Norse mythology, Bifröst is the burning rainbow bridge connecting the realms, and Hǫfuð (Hofund) is the sword of Heimdall, guardian of the bridge. As Heimdall keeps watch over the crossing, pi-hofund watches the connection between Pi and Bifrost, ensuring models, tools, skills, and governance flow smoothly across.

Development

npm run check          # Typecheck with tsc
npm run test           # Run Vitest test suite
npm run lint           # Lint with oxlint
npm run format:check   # Check code formatting with oxfmt

For guidelines on architecture and invariants, consult:

License

Mozilla Public License 2.0 (MPL-2.0).