@restranger/repi-model-fallback0.0.1-ca9b82c

Automatic model fallback and retry for pi-coding-agent

restranger Published 1 hour ago MIT ~531 downloads/mo

Untested on omp

This is a pi package. No one has reported whether it works on omp yet. If you try it, add your result below.

Reports 0

No reports yet.

Readme

@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

Pi executes a turn. If the provider fails (e.g. 403 Forbidden, 429 Rate Limit, 500 Server Error), the turn ends with an error.
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.
The fallback model produces the final answer without requiring user intervention.

Configuration

Configurations are loaded with project priority:

$XDG_CONFIG_HOME/repi/model-fallback.json (or ~/.config/repi/model-fallback.json)
<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

Field	Description	Default
`enabled`	Whether automatic model fallback is active.	`true`
`fallbacks`	Ordered list of models to try if the current model fails. Exact `provider/id` or fuzzy model name.	`[]`
`maxRetriesPerTurn`	Maximum number of consecutive fallback attempts per user prompt before stopping.	`3`
`notify`	Whether to show an informative UI notification on fallback.	`true`

Accepted aliases for compatibility: fallback_models, fallbackModels, max_retries_per_turn.

Slash command & TUI Menu

/fallback — Open the interactive TUI menu to view and manage fallbacks for all agents:
- Lists the primary agent (Main Agent) and all declared subagents (Explore, Plan, general-purpose, etc.).
- Shows primary model and configured fallback chains for each agent.
- Press a or Enter to open the model picker and add any available model from the registry.
- Press d to remove a fallback model.
- Press s to save changes to .repi/model-fallback.json and .repi/subagents.json.
- Press q or Esc to close.
/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.