pi-hofund
Bifrost AI Gateway control-plane extension for Pi (models, MCP, skills, prompts)
Package details
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
compatflags. 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-hofundfront-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:zlibfor 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:
- Bifrost URL — the mount URL of your gateway (e.g.
https://bifrost.example.com/openai/v1). - 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 onGET /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:reloadat 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-gooverride attachesx-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-hofundqueries 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-hofundin theirSKILL.mdfront-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:
- CLI Flags:
--hofund-url,--hofund-api-key,--hofund-virtual-key - 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).
- Settings File:
~/.pi/agent/settings.json(hofund.*block). - 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.mdfor 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:
docs/ATLAS.md— Architecture reference, invariants, and module map.docs/code.md— Code style and formatting rules.docs/extending.md— Adding custom upstream overrides or surfaces.