@restranger/repi-model-fallback

Automatic model fallback and retry for the primary Pi agent. When a model request fails (rate limit, quota exceeded, 403/5xx errors, network failure), this extension automatically switches the active session to the next configured fallback model and transparently resumes execution.

Installation

pi install npm:@restranger/repi-model-fallback
# or from this monorepo
pi --extension ./packages/model-fallback/src/index.ts

How it works

1. Pi executes a turn. If the provider fails (e.g. 403 Forbidden, 429 Rate Limit, 500 Server Error), the turn ends with an error.
2. Before the session settles, @restranger/repi-model-fallback intercepts agent_before_settle:
   • Selects the next viable candidate from your fallbacks list.
   • Activates the fallback model via pi.setModel(nextModel).
   • Omits the failed assistant message via context_edit so the context is clean.
   • Shows a notification in the UI (Model "..." failed: ... Falling back to "...").
   • Returns { continue: true } to immediately prompt the new model.
3. The fallback model produces the final answer without requiring user intervention.

Configuration

Configurations are loaded with project priority:

1. $PI_CODING_AGENT_DIR/extensions/repi-model-fallback.json (default ~/.pi/agent/extensions/repi-model-fallback.json)
2. <project>/.pi/extensions/repi-model-fallback.json or <project>/.repi/model-fallback.json (wins over user config)

{
  "version": 1,
  "enabled": true,
  "fallbacks": [
    "gemini-3.8-flash",
    "anthropic/claude-3-5-sonnet",
    "openai/gpt-4o"
  ],
  "maxRetriesPerTurn": 3,
  "notify": true
}

Options

Accepted aliases for compatibility: fallback_models, fallbackModels, max_retries_per_turn.

Slash command & TUI Menu

• /fallback — Open the interactive menu to view and manage fallbacks for all agents. It renders the same way as Pi's own pickers (/models, /llama, ctx.ui.select): an inline frame in the editor slot, a → cursor, muted descriptions and a key-hint line, with no full-screen overlay.
  • Lists the primary agent (Main Agent) and all declared subagents (Explore, Plan, general-purpose, etc.).
  • Shows the selected agent's primary model and fallback chain below the list.
  • Press a or Enter to open the model picker, then type to fuzzy-search the registry.
  • The picker works like /scoped-models: Enter toggles the highlighted model, Ctrl+A enables every model in the filtered list, Ctrl+X clears it, Ctrl+P toggles the selected model's provider and Alt+↑/↓ reorders the fallback chain. Enabled models are listed first, in chain order, with a #n rank; chain entries that are no longer available stay listed as [unavailable] so they can be removed.
  • Press Ctrl+S (or s on the agent list) to save. The fallback chain goes to the user config (<agentDir>/extensions/repi-model-fallback.json, normally ~/.pi/agent/...) so it follows the user and works in an untrusted workspace; a trusted project that already owns a fallback config is updated in place. Subagent overrides are applied in memory and persisted by @restranger/repi-subagents when the workspace is trusted. Unsaved edits are marked unsaved in the subtitle.
  • Press q or Esc to close; in the picker Esc first clears the search, then returns.
• /fallback status — Print status overview in text mode.
• /fallback list — List configured fallbacks and all available models in the registry.
• /fallback on — Enable fallback for the current session.
• /fallback off — Temporarily disable fallback.
• /fallback reload — Reload configuration files from disk.

Typing /fallback and pressing Tab completes these subcommands; nothing is offered after a subcommand because the rest of the argument is not a fixed slot.