pi-auto-fallback

Provider-agnostic automatic fallback for Pi.

Requires Pi >= 0.81.0 and Node.js >= 22.19.0.

It does not hard-code provider implementations. It uses Pi's current model registry, so any model visible to Pi can participate in a fallback chain, including providers from models.json and provider extensions such as opencode-go.

Behavior

Example chain:

BAI/gpt-5.6-sol
  -> transient 524/timeout/429/5xx
opencode-go/deepseek-v4-pro
  -> transient failure
opencode-go/glm-5.2

Safety default: if a tool has already started executing during the logical request, automatic replay is disabled to avoid repeating side effects.

Install from local directory

unzip pi-auto-fallback.zip
pi install /absolute/path/to/pi-auto-fallback

Or copy it directly into Pi's extension directory:

mkdir -p ~/.pi/agent/extensions/pi-auto-fallback
cp extensions/index.ts ~/.pi/agent/extensions/pi-auto-fallback/index.ts

Pi supports TypeScript extensions directly. After installation/replacement, run:

/reload

Configure

cp auto-fallback.example.json ~/.pi/agent/auto-fallback.json

Edit ~/.pi/agent/auto-fallback.json and use exact model keys from:

pi --list-models

A provider/model key is split only on the first /, so model IDs may themselves contain /.

If PI_CODING_AGENT_DIR is set, the extension reads $PI_CODING_AGENT_DIR/auto-fallback.json instead. Missing or invalid configuration is fail-closed: fallback remains disabled. /fallback-reload keeps the last valid configuration if the replacement file is invalid.

Commands

/fallback-status
/fallback-reload
/fallback-reset

Important safety rule

requireNoToolCalls defaults to true.

Keep this enabled for coding agents. A retry after a tool has already modified files, run commands, sent requests, or performed another side effect can duplicate actions.

Retryable by default

• HTTP 408, 409, 425, 429
• HTTP 5xx, including Cloudflare 524
• timeout / socket / connection reset/refused errors
• overloaded / unavailable / resource exhausted

Authentication, invalid-model, forbidden, and context-window errors are treated as non-retryable.

How retry works

Pi performs its built-in same-model retry and compaction recovery first. Only if the final settled assistant message still contains a retryable error does this extension switch to the next registered model and inject a short retry instruction.

Pi preserves the original user turn in session context. The extension therefore does not duplicate the original text/image message, avoiding duplicate image payloads while still re-running the request on the fallback model.

Development

npm install
npm run check

The checks run strict TypeScript validation, focused state-machine/configuration tests, and a package-content dry run.