# Usage

## Commands

### `/models`

Browse all available models across all configured servers.

```
/models
```

Displays an interactive menu with:
- Model name (using server aliases if available, otherwise model ID)
- Status icon (🟢 loaded, 🟡 loading, 🔴 failed, 🔵 sleeping, ⚪ unloaded, ⛔ unauthorized)
- Server URL in brackets

**Actions available per status:**

| Status | Available Actions |
|--------|------------------|
| 🟢 Loaded | Switch, Info, Cancel |
| 🟡 Loading | Info, Cancel |
| 🔴 Failed | Retry, Info, Cancel |
| 🔵 Sleeping | Switch, Unload, Info, Cancel |
| ⚪ Unloaded | Load & Switch, Load, Cancel |
| ⛔ Unauthorized | Info, Cancel |

> **Note:** "Unload" is only available in router mode. Single-model and legacy-model servers only have one model, so unloading is not applicable.

### `/models info`

Show detailed information for all models at once.

```
/models info
```

Displays:
- Server URL
- Model ID
- Model name (alias)
- Reasoning support
- Capabilities (text, image)
- Context size
- Current status

### `/models unload`

Unload all loaded models at once.

```
/models unload
```

> **Note:** Only meaningful in router mode.

### `/login`

Configure authentication for your providers.

```
/login              # Interactive selector
/login Lite         # Filter by name
/login gateway-3a4b5c6d  # Short hash-based provider ID
```

## Model Actions

### Load & Switch

Load an unloaded model and switch to it immediately.

### Switch

Switch to a model that is already loaded (no reload needed).

### Unload

Unload a loaded model to free memory.

### Retry

Retry loading a failed model.

### Info

View detailed model information.

### Cancel

Cancel the current operation.

## Loading Models

When you trigger a load, the extension uses:

1. **SSE (Server-Sent Events)** — Real-time progress updates (default for llama.cpp servers)
2. **Polling** — Fallback when SSE is unavailable (used for LiteLLM proxies)

### Progress Tracking

With SSE, you'll see real-time progress updates:

```
Loading llama3.gguf... [45% loading]
Loading llama3.gguf... [100% loaded]
```

### Timeout

If loading takes longer than **60 seconds**, the operation times out with an error.

> **Note:** The timeout only applies to progress detection. The model might still be loading in the background. Use `/models` to check the status.

## Thinking Budgets

Control how many tokens the model allocates to reasoning/thinking.

### Selecting a Level

Use Pi's built-in thinking level selector. The extension maps each level to a token budget:

| Level | Tokens | Behavior |
|-------|--------|----------|
| `off` | 0 | Thinking disabled (`chat_template_kwargs.enable_thinking: false`) |
| `minimal` | 1,024 | Short reasoning steps |
| `low` | 2,048 | Light reasoning |
| `medium` | 8,192 | Balanced reasoning (default) |
| `high` | 16,384 | Extended reasoning |
| `xhigh` | -1 | Unlimited reasoning |
| `max` | -1 | Unlimited reasoning (maximum depth) |

### Custom Budgets

Override defaults in your settings:

```json
{
  "thinkingBudgets": {
    "minimal": 256,
    "low": 1024,
    "medium": 2048,
    "high": 4096
  }
}
```

Only `minimal`, `low`, `medium`, and `high` are configurable.

## Model Selection Event

When you switch models via Pi's model picker (instead of the `/models` command), the extension automatically loads the requested model before the conversation begins.

This keeps the server in sync with the active model in Pi, regardless of how the switch was initiated.

> **Note:** If you switch sessions while a model load is in-flight, you'll see a warning, but the load continues in the background. Use `/models` in the new session to verify the model status.

## Model Configuration

Each model exposed to Pi includes:

- **`maxTokens`** — Dynamically set to the model's context window (detected from llama-server)
- **`reasoning`** — `true` (assumed, as llama.cpp's `/v1/models` endpoint does not expose this)
- **`cost`** — All zero (local models)
- **`thinkingLevelMap`** — Maps Pi's thinking levels to provider-specific level names

## Context Size Detection

The extension determines context size as follows:

| Mode | Detection Method | Fallback |
|------|-----------------|----------|
| Router | `meta.n_ctx` from `/v1/models` | `--ctx-size` / `--fit-ctx` from server args |
| Single | `meta.n_ctx` from `/v1/models` | 128,000 tokens |
| Legacy | `max_model_len` from `/v1/models` | `n_ctx` from `/props` |

## Image Capabilities

The extension detects multimodal models automatically:

1. **When loaded:** Reads `modalities.vision` from `/props`
2. **When not loaded:** Reads `architecture.input_modalities` from `/v1/models`

Models with image support are tagged with `["text", "image"]` capabilities.