# pi-fastmode-web

Pi extension: automatic Fast Mode for GPT-5 sessions in pi CLI and pi-web.

[中文版说明](README.zh-CN.md)

## Behavior

Fast Mode is **Auto on startup** by default.

For trusted tier providers, Fast Mode keeps the current GPT-5 model and requests OpenAI's fast tier by adding `service_tier: "fast"` to provider requests:

- `openai`
- `openai-codex`

`FAST · tier requested` means the extension requested the tier. It is not proof that the upstream provider honored it. If the upstream reports `default`, keeping the model does not provide an actual speed increase.

For all other providers, Fast Mode never crosses providers and never sends `service_tier`. Instead, it switches to the first available fallback model on the same provider. The default fallback order is:

1. `gpt-5.3-codex-spark`
2. `gpt-5.4-mini`

If no same-provider fallback is registered, Fast Mode reports unsupported and leaves the model unchanged.

## Install

```bash
pi install npm:pi-fastmode-web
# or project-local
pi install -l npm:pi-fastmode-web
```

Restart pi / pi-web after install.

> Not published yet? Install from source:
>
> ```bash
> pi install ./path/to/pi-fastmode-web
> ```

## Commands

```text
/fast status
/fast
/fast on
/fast off
```

`/fast` is the same as `/fast status`. It does not toggle Fast Mode.

`/fast on` enables Auto behavior again and applies it to the current model.

`/fast off` disables Fast Mode. If Fast Mode auto-switched to a fallback model, it restores the original model and original thinking level.

## Statuses

| Status | Meaning |
| --- | --- |
| `FAST · tier requested` | Current trusted-tier GPT-5 model is kept, and `service_tier` will be requested on provider calls |
| `FAST · model <id>` | Current model is already a fallback or was switched to fallback model `<id>` |
| `FAST · unsupported` | No trusted-tier path or same-provider fallback is available |
| `FAST · off` | Fast Mode is disabled |

## Configuration

Optional. Create a JSON file to override defaults:

**User-level**: `~/.pi/agent/extensions/pi-fastmode-web/config.json`

**Project-level** (overrides user-level): `<project>/.pi/pi-fastmode-web/config.json`

```json
{
  "enabled": true,
  "tierProviders": ["openai", "openai-codex"],
  "fallbackModels": ["gpt-5.3-codex-spark", "gpt-5.4-mini"],
  "serviceTier": "fast"
}
```

| Field | Default | Description |
| --- | --- | --- |
| `enabled` | `true` | Auto on startup |
| `tierProviders` | `["openai", "openai-codex"]` | Providers that may receive `service_tier` for GPT-5 models |
| `fallbackModels` | `["gpt-5.3-codex-spark", "gpt-5.4-mini"]` | Same-provider fallback model order for other providers |
| `serviceTier` | `"fast"` | The `service_tier` value requested for trusted tier providers |

Legacy `providers` is ignored. Legacy `serviceTier: "priority"` is normalized to `"fast"`.

## Requirements

- `@earendil-works/pi-coding-agent` 0.83.0+ (pi CLI 0.83.0+ / pi-web 0.8.x)
- A trusted tier provider must support `service_tier`; other providers use same-provider model fallback instead

## License

MIT