Pi-Bifrost

Getting started · Configuration · Classifier backends · Troubleshooting · Examples · Development

What Bifrost does

Pi-Bifrost chooses a suitable model for each message from the models you allow. You spend less time selecting and switching models by hand.

A tier is a named model group, such as quick or general. A classifier is an extra AI call that chooses a tier. It cannot choose a model outside your lists.

Router SDK

Use Bifrost's routing engine without running Pi. Other applications can give Bifrost their model inventory and configuration, and get back an advisory, inspectable route decision they execute themselves.

import { createRouter } from "pi-bifrost/router";

The Pi packages are optional peer dependencies; a standalone consumer installs the package without Pi, API keys, or network access on the default path. See docs/router-api.md and the shipped examples/router-standalone.mjs plus examples/host-adapter.mjs.

Install

Connect and sign in to a model provider in Pi before you install Bifrost.

pi install npm:pi-bifrost

Fresh installs route by default. Before Pi sends your message, Bifrost chooses the active model in Pi.

When no route file, meaningful configuration, runtime routing preference, or explicit routing override blocks setup, Bifrost loads provisional model lists from Pi's catalog before it sends your first message. It checks model access in the background, then saves only successful generated pools to .pi/bifrost.json. An empty {} file does not block setup. A configuration with settings does.

Provisional pools are catalog entries, not proof that a model works. Background probes send small provider requests and can use credits or reach rate limits. If no model passes, Bifrost leaves configuration unchanged and warns you. The generated configuration adds no prompts or credentials. See Getting started.

Select bifrost/auto in Pi's /model picker to let Bifrost choose which model answers each message. The footer shows Auto and the selected model. Use /bifrost inspect or /bifrost debug to see model lists and status without a classifier call. Pi's list does not prove a model will work.

sequenceDiagram
    participant You
    participant Bifrost
    participant Model
    You->>Bifrost: First prompt resolves to general
    Bifrost->>Model: Strategy selects model A
    Model-->>Bifrost: Successful Auto turn
    Note over Bifrost: Keep A for later general turns if A remains eligible
    You->>Bifrost: Prompt starts with quick
    Bifrost->>Model: Use quick tier strategy

Run /bifrost init to refresh Pi's model list or reconcile model pools. It reuses probe results from the last hour; otherwise it checks models before it proposes changes. Pass -f to force fresh probes. Probes can use credits or reach rate limits. Init preserves other configuration fields and handwritten model entries. It asks once before saving, but its summary does not list every model ID or how Bifrost chooses among models.

By default, Auto can keep a successful model for later messages in the same tier while it remains allowed. A different tier uses its own model selection rule. See Auto routing.

Configure tiers

Edit your existing configuration to keep its model lists and settings. If you have no configuration, init can save starter lists first.

{
  "default": "general",
  "models": {
    "quick": ["provider/fast-model"],
    "general": ["provider/general-model"],
    "frontier": ["provider/frontier-model"]
  }
}

Replace the example IDs with models available in Pi. The configuration guide explains strategies, rules, reserves, billing preferences, and fallback tiers.

Describe the goal instead

Bifrost ships a configure-bifrost skill and a bifrost_config tool, so you can describe the outcome you want instead of assembling the JSON yourself:

Configure Bifrost for my coding workflow: cheap implementation with a strong
orchestrator and an independent reviewer, and no silent escalation to an
expensive model. Use the models I already have.

The agent reads Pi's real model list and your config files. It builds a candidate policy, checks it, previews routes offline, and explains the tradeoffs. It shows a tool-generated impact summary first. Nothing is written before you agree, and one config file is written atomically. The agent does not change how Bifrost routes; it only writes the configuration you approve. Apply requires Pi's terminal UI (TUI). Press a to apply the summary, or press d to inspect every exact change. In exact view, press n or p to move through pages, b to return to the summary, and a on the last page to apply. Summary approval does not mean you inspected every value. Escape cancels. Resizing returns to the summary. Terminals smaller than 40 columns or 8 rows cannot approve.

The exact view uses JSON escapes so values remain exact. Proposals above the 2,000,000-character review limit fail before the dialog and write nothing. RPC sessions can inspect, check, and preview, but apply returns approval_required: Pi's RPC protocol cannot prove that clients display every change. Use a TUI to check and approve the proposal again.

You can also ask for the single tool directly. It has four operations: inspect, check, preview, and apply. See the skill.

Inspect and control routes

Use these commands in Pi:

Command	Result
/bifrost preview --offline <prompt>	Show a route using local cache and rules. Makes no classifier request.
quick <message>	Use the quick tier once. Bifrost removes its name before sending the prompt.
/bifrost pin / /bifrost unpin	Keep the model or resume routing.
/bifrost off / /bifrost on	Stop or resume routing.
/bifrost classifier off	Stop the extra AI call for this Pi session.
/bifrost cache stats / /bifrost cache clear	View or empty saved entries.

See all commands and routing controls.

Privacy and reliability

The classifier is on by default. The local cache saves earlier routing decisions. It stores simplified words from prompts and the chosen tier. Treat these as sensitive. Bifrost does not cache answers. If the cache has no matching decision, the classifier can receive the prompt.

/bifrost classifier off stops this call for the current Pi session. It works without a Bifrost configuration file and does not save a toggle. After restart, Bifrost uses classifier.enabled. If legacy state says false while config says true, classification pauses until a session choice. Pi still sends the prompt to your selected model service.

To stop using the local cache, add "cache": { "enabled": false } inside your existing configuration. Keep its model lists. This stops cache lookups and new classification entries. It does not clear saved entries. /bifrost cache clear empties them. If you have no configuration, run /bifrost init first. See reliability and local cache.

By default, a usage or billing rejection pauses all models with the same configured Pi provider ID. This applies to Auto and physical routing. It does not identify shared billing accounts. Set reliability.allowanceCooldownScope to model to limit the pause to one model. See provider pauses.

Auto can try another allowed model once after a usage or billing rejection only when reliability.retryOnAllowanceExhausted is true. Pi must prove the failed turn was empty and safe to continue. The provider pause still applies when you disable the retry. See Auto routing for the full limits.

Bifrost saves model failures locally and can stop using a model for a time. Bifrost does not fetch live usage limits from model services. See the reliability guide and its migration steps. Model changes can reduce prompt-cache reuse. Providers control cache use and billing. See provider prompt caching.

Set reliability.retryOnAllowanceExhausted to true to opt in to the one Auto retry. Use /bifrost reliability to see active provider pauses. See all commands for how to reset one provider pause.

Advanced

Bifrost Patterns · Experimental resolve-only router API for Node.js.

License

MIT. See LICENSE.