---
slug: "pi-models"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/apmantza/pi-models@master/README.md"
repo: "https://github.com/apmantza/pi-models"
source_file: "README.md"
branch: "master"
---
# Pi Models Extension

**Browse and switch AI models in Pi with an intuitive cascading menu.**

This extension adds a `/models` command to [Pi](https://github.com/badlogic/pi-mono) that opens an interactive model browser. Instead of typing model IDs, you can visually navigate through providers and model families to find and switch models instantly.

---

## What This Is

Pi Models replaces manual model switching with a point-and-select interface:

- **Visual browsing** - See all available models organized by provider or family
- **Three browsing modes** - Choose your navigation style: by provider, lab, or model family
- **Smart grouping** - Automatically groups models into families (GPT-4, Claude, Llama, etc.)
- **Multi-provider awareness** - When the same model is available from multiple providers (e.g., Claude via Anthropic, AWS, or Vertex), you choose which one to use
- **Free model discovery** - All free models from any provider grouped together at the top
- **No truncation** - Full model names are displayed with dynamic column sizing
- **Live catalog metadata** - Families and labs are enriched from [models.dev](https://models.dev)

### Live model metadata

When `/models` opens, the extension fetches `api.json` and `catalog.json` from models.dev. Their family and canonical lab metadata is applied to the models already available in Pi, so new families appear without an extension release. Pi's registry remains the source of the selectable models because it knows which providers have credentials and which local models are installed.

The catalog is cached for the current Pi session. If models.dev is unavailable, the existing local family heuristic is used automatically. Family labels include detected versions such as Gemma 4, GPT 5, GLM 4/5, and MiniMax 2.5/2.7/3.

---

## How to Use It

### 1. Open the Browser

Type `/models` in Pi's input box and press Enter:

```
User: /models
Pi: [Model browser opens]
```

### 2. Choose Browse Mode

First, pick how you want to browse:

```
📦 Browse Models
→ 📦 By Provider          ← Browse provider → model
  🔬 By Lab               ← Browse lab → all models from that lab
  🏷️ By Model Family     ← Browse family → provider → model
```

| Mode                | Best For                                                    | Flow                                 |
| ------------------- | ----------------------------------------------------------- | ------------------------------------ |
| **By Provider**     | When you know which provider hosts the model                | Provider → Model                     |
| **By Lab**          | When you want to see all models from a specific lab/company | Lab → All Models                     |
| **By Model Family** | When you know the model type and want family filtering      | Family → Provider (if multi) → Model |

**Navigate:** ↑/↓ or k/j to move, Enter to select, Esc to cancel

### 3. Browse and Select

#### By Provider View

```
📦 Models                    📦 anthropic
→ 🆓 Free Models (3)         → ● claude-sonnet-4-20250514
  anthropic (8)                claude-haiku-3-20240307
  google (4)                   claude-opus-4-20250514
  openai (6)
  ollama (12)
```

1. Select a provider (or 🆓 Free Models)
2. See all models for that provider
3. Select a model to switch to it

#### By Model Family View

```
🏷️ Model Families            🏷️ Claude Sonnet
→ 🆓 Free Models (3)         → anthropic
  Claude Haiku (2)             aws
  Claude Opus (2)              vertex
  Claude Sonnet (3)
  GPT-4o (4)
  Llama 3.3 (5)
```

1. Select a model family (or 🆓 Free Models)
2. **If multiple providers:** Choose which provider's version
3. **If single provider:** Latest version is selected automatically
4. Model switches instantly

### 4. Model Switches Automatically

After selection, Pi immediately switches to that model:

```
[System: Switched to claude-sonnet-4-20250514]
```

---

## Supported Model Families

The extension uses models.dev family metadata when available and falls back to pattern matching on model IDs and names when a model is not in the catalog:

| Family           | Pattern              | Example IDs Matched                                      |
| ---------------- | -------------------- | -------------------------------------------------------- |
| **ByteDance**    | `bytedance`          | `bytedance-doubao`, `bytedance-seed`                     |
| **Claude**       | `claude`             | `claude-opus-4`, `claude-sonnet-3.5`, `claude-haiku-3`   |
| **Cohere**       | `cohere`             | `cohere-command`, `cohere-embed`                         |
| **Command**      | `command`            | `command-r-plus`, `command-r`, `command-light`           |
| **Doubao**       | `doubao`             | `doubao-pro-32k`, `doubao-lite-128k`, `bytedance-doubao` |
| **E5**           | `e5`                 | `e5-large`, `e5-base-v2`, `intfloat/e5`                  |
| **GPT**          | `gpt`                | `gpt-4o`, `gpt-4-turbo`, `gpt-3.5-turbo`, `o1-preview`   |
| **Gemini**       | `gemini`             | `gemini-1.5-pro`, `gemini-1.5-flash`, `gemini-ultra`     |
| **Llama**        | `llama`              | `llama3.2`, `llama-3.3-70b`, `codellama-70b`             |
| **DeepSeek**     | `deepseek`           | `deepseek-chat`, `deepseek-r1`                           |
| **Qwen**         | `qwen`               | `qwen3.5-397b`, `qwen3-coder`, `qwen3-vl`                |
| **MiniMax**      | `minimax`            | `minimax-m2.5`, `minimax-m2`                             |
| **Kimi**         | `kimi` or `moonshot` | `kimi-k2.5`, `moonshot-v1-32k`                           |
| **GLM**          | `glm` or `chatglm`   | `glm-4.7`, `glm-5`, `chatglm3`                           |
| **Nemotron**     | `nemotron`           | `nemotron-4-340b`, `nemotron-3-super`                    |
| **Mistral**      | `mistral`            | `mistral-large-3`, `mistral-small`                       |
| **BGE**          | `bge`                | `bge-large-en-v1.5`, `bge-base-en-v1.5`, `bge-m3`        |
| **Arcee**        | `arcee` or `trinity` | `trinity-large-preview`, `arcee-ai/trinity-mini`         |
| **Hermes**       | `hermes`             | `hermes-2-pro`, `hermes-3-llama`                         |
| **Hy3**          | `hy3`                | `hy3-70b`, `hy3-lite`                                    |
| **HY 2.0**       | `hy2`                | `hy2-7b`, `hy2-33b`                                      |
| **Inclusion AI** | `inclusion`          | `inclusion-ling`, `inclusion-llada2`, `inclusion-ring`   |
| **Laguna**       | `laguna`             | `laguna-3b`, `laguna-7b`, `poolside-laguna`              |
| **Ling**         | `ling`               | `ling-1`, `ling-v2`, `inclusion-ling`                    |
| **Llada2**       | `llada`              | `llada2-7b`, `llada2-13b`, `inclusion-llada2`            |
| **Lyria**        | `lyria`              | `lyria-1`, `lyria-v2`                                    |
| **Veo 2**        | `veo2`               | `veo2`, `veo2-create`                                    |
| **Ring**         | `ring`               | `ring-1`, `ring-v2`, `inclusion-ring`                    |
| **Poolside**     | `poolside`           | `poolside-laguna`, `poolside-assist`                     |
| **LFM 2**        | `lfm2`               | `lfm2-7b`, `lfm2-40b`                                    |
| **Qianfan**      | `qianfan`            | `qianfan-chat`, `qianfan-ernie`                          |
| **Other**        | `router`, `auto`     | Router models grouped separately                         |

**Multi-Provider Grouping:** Models with the same name from different providers (e.g., `Trinity Large Preview` from zen, kilo, cline) are automatically merged into the same family.

**Ollama Models:** Local Ollama models are grouped with their brand families (e.g., `ollama/llama3.2` → Llama family, `ollama/qwen2.5` → Qwen family).

---

## Development

### Running Tests

The extension includes an 81-test suite covering model family detection, grouping, models.dev enrichment, and utility functions:

```bash
# Install dependencies
npm install

# Run tests once
npm test

# Run tests in watch mode during development
npm run test:watch

# Type check
npm run typecheck
```

### Test Coverage

| Area                    | Coverage                                      |
| ----------------------- | --------------------------------------------- |
| `isModelFree()`         | Pricing and name-based free-model detection   |
| `detectModelFamily()`   | Brand patterns, routers, fallbacks             |
| Grouping helpers        | Providers, families, labs, and name merging   |
| models.dev enrichment   | Live family/lab metadata and missing matches  |

**Total: 81 tests** covering all major functionality and edge cases.

---

## Installation

### Via pi install (recommended)

```bash
pi install npm:pi-models
```

This installs the package and adds it to your `settings.json` automatically. Run `/reload` in Pi to activate.

### Via settings.json

Add to `~/.pi/agent/settings.json`:

```json
{
  "packages": ["npm:pi-models"]
}
```

Then run `/reload` in Pi.

### Via GitHub (manual)

```bash
cd ~/.pi/agent/extensions
git clone https://github.com/apmantza/pi-models.git
```

Or copy just the file:

```bash
cp pi-models.ts ~/.pi/agent/extensions/
```

Run `/reload` in Pi.

---

## Controls Reference

| Key                    | Action                                    |
| ---------------------- | ----------------------------------------- |
| `↑` / `↓` or `k` / `j` | Navigate up/down                          |
| `Enter`                | Select highlighted item                   |
| `Esc`                  | Go back to previous level / close browser |

---

## Requirements

- Pi v1.0+ with TypeScript extension support
- Models must have configured auth (API keys or local dummy keys like `"ollama"`)

---

## Changelog

### Unreleased

- **New:** Enrich model families and labs from models.dev at runtime
- **Improved:** New models.dev families no longer require a manual extension update
- **Improved:** Free model variants are merged with their base families

### 0.2.6

- **Fixed:** 5 CodeQL ReDoS alerts in `normalizeModelName` — polynomial backtracking eliminated

### 0.2.5

- **New:** BGE model family (BAAI lab)
- **New:** E5 model family (Intfloat lab)
- **New:** Veo 2 model family (Google lab)
- **New:** HY 2.0 model family (Tencent lab)
- **New:** LFM 2 model family (Liquid lab)

### 0.2.3

- **New:** Hermes, Hy3, Lyria, and Qianfan model family support
- **New:** Provider count shown in "By Model Family" view (e.g., "Claude Sonnet (3)")
- **Improved:** Overlay screens auto-resize to fit content width

### 0.2.2

- **Fixed:** OpenAI o4 models now correctly group under OpenAI lab (added "o4" to o-series detection)
- **Fixed:** By Lab view now shows all models directly without intermediate family selection step

### 0.2.1

- **Fixed:** Ollama models now group with brand families instead of separate `ollama-*` families
- **New:** Name-based family merging - models with same name from different providers auto-merge
- **New:** Arcee/Trinity model family support
- **New:** Router models (`router`, `auto`, `kilo-auto/free`) grouped into "Other" family
- **New:** Mistral model family support
- **New:** Complete test suite (60 tests)

### 0.2.0

- **New:** Browse mode selection (By Provider / By Model Family)
- **New:** Automatic model family detection with heuristic pattern matching
- **New:** Multi-provider selection for same model families (e.g., Claude from Anthropic/AWS/Vertex)
- **Improved:** Dynamic column sizing - model names are no longer truncated
- **Improved:** Wider overlays for better visibility
- **Improved:** Free Models accessible in both browse views

### 0.1.0

- Initial release
- Two-level provider → model browsing
- Free models virtual provider
- Local model support (Ollama)

---

**Author:** Apostolos Mantzaris  
**License:** MIT