pi-free 2.0.5 → 2.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +495 -495
  2. package/lib/open-browser.ts +31 -4
  3. package/lib/util.ts +351 -262
  4. package/package.json +1 -1
  5. package/provider-failover/benchmark-lookup.ts +702 -688
  6. package/scripts/check-extensions.mjs +18 -11
package/README.md CHANGED
@@ -1,495 +1,495 @@
1
- # pi-free-providers
2
-
3
- <p align="center">
4
- <img src="banner.svg" alt="pi-free" width="100%" max-width="900">
5
- </p>
6
-
7
- Free and paid AI model providers for [Pi](https://pi.dev). Access **free and paid models** from multiple providers in one install.
8
-
9
- ---
10
-
11
- ## What does pi-free do
12
-
13
- **pi-free is a Pi extension that unlocks free and paid AI models from multiple providers.**
14
-
15
- When you install pi-free, it:
16
-
17
- 1. **Registers free-tier providers** with Pi's model picker — Kilo (free), Cline (free), NVIDIA (freemium), ZenMux (paid), CrofAI (paid), Ollama Cloud (freemium), and more
18
-
19
- 2. **Fetches models dynamically** from provider APIs — NVIDIA NIM, ZenMux, CrofAI, and Pi's built-in providers (Mistral, Groq, Cerebras, xAI, Hugging Face, OpenRouter) when API keys are configured
20
-
21
- 3. **Filters to show only free models by default** for providers that expose pricing — You see only the models that cost $0 to use. Paid models are hidden until you explicitly toggle them on.
22
-
23
- 4. **Provides per-provider toggle commands** — Run `/toggle-{provider}` (e.g., `/toggle-kilo`, `/toggle-opencode`) to switch between free-only mode and showing all models including paid ones. Changes apply immediately and your preference is saved for the next Pi restart.
24
-
25
- 5. **Handles authentication for you** — OAuth flows (Kilo, Cline) open your browser automatically; API keys are read from `~/.pi/free.json` or environment variables
26
-
27
- 6. **Adds Coding Index scores** — Model names include a coding benchmark score (CI: 45.2) to help you pick capable coding models at a glance
28
-
29
- 7. **Persists your preferences** — Your toggle choices (free vs all models) are saved to `~/.pi/free.json` and remembered across Pi restarts
30
-
31
- ---
32
-
33
- ## How to use
34
-
35
- ### 1. Install the extension
36
-
37
- ```bash
38
- pi install git:github.com/apmantza/pi-free
39
- ```
40
-
41
- ### 2. Open the model picker
42
-
43
- Start Pi and press `Ctrl+L` to open the model picker.
44
-
45
- Free models are shown by default — look for the provider prefixes:
46
-
47
- **✅ Free Models (no payment required):**
48
-
49
- - `opencode/` — OpenCode models (no setup required; toggle with `/toggle-opencode`)
50
- - `kilo/` — Kilo models (free models available immediately, more after `/login kilo`)
51
- - `openrouter/` — OpenRouter models (free account required)
52
- - `cline/` — Cline models (run `/login cline` to use)
53
-
54
- **🔄 Freemium (free tier with limits, then paid):**
55
-
56
- - `nvidia/` — NVIDIA NIM models (1,000 free requests/month, then credits)
57
- - `ollama-cloud/` — Ollama Cloud models (usage-based free tier, resets every 5 hours + 7 days)
58
- **💳 Paid Providers (API key with credits required):**
59
-
60
- - `zenmux/` — ZenMux AI gateway (200+ models from OpenAI, Anthropic, Google, etc.)
61
- - `crofai/` — CrofAI OpenAI-compatible API (streaming, reasoning models)
62
-
63
- > **Note:** Paid providers may occasionally offer free models or promotional credits. The `isFreeModel` helper automatically detects free models based on provider pricing data or model names containing "free". For providers that don't expose pricing (like CrofAI), only models with "free" in their names are marked as free.
64
-
65
- **🔧 Dynamic API Providers (fetched when API key configured):**
66
-
67
- - `mistral/` — Mistral models (when `MISTRAL_API_KEY` set)
68
- - `groq/` — Groq models (when `GROQ_API_KEY` set)
69
- - `cerebras/` — Cerebras models (when `CEREBRAS_API_KEY` set)
70
- - `xai/` — xAI models (when `XAI_API_KEY` set)
71
- - `huggingface/` — Hugging Face models (when `HF_TOKEN` set)
72
-
73
- **Note:** Fireworks is now a [built-in Pi provider](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/CHANGELOG.md#0681---2026-04-22) — no extension needed. Set `FIREWORKS_API_KEY` to use it directly.
74
-
75
- ### 3. Toggle between free and paid models
76
-
77
- Want to see paid models too? Run the toggle command for your provider:
78
-
79
- ```
80
- /toggle-opencode # Toggle OpenCode (✅ offers free models)
81
- /toggle-kilo # Toggle Kilo (✅ offers free models)
82
- /toggle-openrouter # Toggle OpenRouter (✅ offers free models)
83
- /toggle-cline # Toggle Cline (✅ offers free models)
84
- /toggle-nvidia # Toggle NVIDIA (🔄 freemium)
85
- /toggle-ollama # Toggle Ollama Cloud (🔄 freemium)
86
- /toggle-mistral # Toggle Mistral (🔧 dynamic - needs API key)
87
- /toggle-groq # Toggle Groq (🔧 dynamic - needs API key)
88
- /toggle-cerebras # Toggle Cerebras (🔧 dynamic - needs API key)
89
- /toggle-xai # Toggle xAI (🔧 dynamic - needs API key)
90
- /toggle-huggingface # Toggle Hugging Face (🔧 dynamic - needs HF_TOKEN)
91
- /toggle-zenmux # Toggle ZenMux (💳 paid - needs API key with credits)
92
- /toggle-crofai # Toggle CrofAI (💳 paid - needs API key with credits)
93
- ```
94
-
95
- **Notes:**
96
-
97
- - **Toggle commands are mainly for ✅ and 🔄 providers** — to switch between "free models only" vs "show paid models too"
98
- - **🔧 Dynamic providers** show all fetched models by default — the toggle filters the list when you have an API key configured
99
- - **Freemium providers** show all models by default; you manage your usage limits via their dashboards
100
-
101
- You'll see a notification like: `opencode: showing free models` or `opencode: showing all models`
102
-
103
- **Note:** Built-in provider toggles such as OpenCode and OpenRouter update in the current session — no restart needed.
104
-
105
- ### 4. Add API keys for more providers (optional)
106
-
107
- Some providers require a free account or API key.
108
-
109
- **The first time you run Pi after installing this extension, a config file is automatically created:**
110
-
111
- - **Linux/Mac:** `~/.pi/free.json`
112
- - **Windows:** `%USERPROFILE%\.pi\free.json`
113
-
114
- Add your API keys to this file:
115
-
116
- ```json
117
- {
118
- "openrouter_api_key": "sk-or-v1-...",
119
- "nvidia_api_key": "nvapi-...",
120
- "ollama_api_key": "...",
121
- "mistral_api_key": "...",
122
- "modal_api_key": "sk-modal-..."
123
- }
124
- ```
125
-
126
- Or set environment variables instead (same names, uppercase: `OPENROUTER_API_KEY`, `NVIDIA_API_KEY`, etc.)
127
-
128
- If `~/.pi/free.json` contains invalid JSON, pi-free now logs the parse error to `~/.pi/free.log` so you can fix the file quickly.
129
-
130
- See the [Providers That Need Authentication](#providers-that-need-authentication) section below for detailed setup instructions per provider.
131
-
132
- ### 5. Quick commands reference
133
-
134
- | Command | What it does |
135
- | -------------------- | --------------------------------------------------------- |
136
- | `/toggle-{provider}` | Switch between free-only and all models for that provider |
137
- | `/free-providers` | Show free/paid model counts for all providers |
138
- | `/login kilo` | Start OAuth flow for Kilo |
139
- | `/login cline` | Start OAuth flow for Cline |
140
- | `/logout kilo` | Clear Kilo OAuth credentials |
141
- | `/logout cline` | Clear Cline OAuth credentials |
142
-
143
- ---
144
-
145
- ## Features
146
-
147
- ### 🔍 NVIDIA: Pre-Filtering + 404 Detection
148
-
149
- NVIDIA's API lists 130+ models, but 57+ return 404 "Function not found" when you try to use them. pi-free solves this:
150
-
151
- - **57 known 404s hard-filtered** — Discontinued models (`dbrx-instruct`, `codellama-70b`), embedding models mislabeled as chat-capable (`nv-embed-*`), and stale catalog entries are silently excluded
152
- - **Auto-discovery from NVIDIA's API** — Queries `integrate.api.nvidia.com/v1/models` directly for the ground-truth list
153
- - **`/probe-nvidia` command** — On-demand health check: tests every model with a minimal request, auto-hides new 404s, and re-registers immediately
154
-
155
- ### 🎯 Coding Index (CI) Scores
156
-
157
- Every model shows a **Coding Index score** (e.g., `CI: 52.3`) in the model picker:
158
-
159
- - **Benchmark-based** — Scores derived from Artificial Analysis coding benchmarks (HumanEval, MBPP, etc.)
160
- - **Quality indicator** — Higher scores = better coding performance
161
- - **All providers** — Applied to every model from every provider (NVIDIA, Mistral, Groq, etc.)
162
-
163
- **Missing CI scores?** Provider model IDs often don't match benchmark database keys exactly. pi-free applies provider-specific normalization to improve matching:
164
-
165
- | Provider | Normalization Applied |
166
- | ------------ | ------------------------------------------------------------------ |
167
- | **NVIDIA** | Strips vendor prefixes (`meta/`, `mistralai/`, `microsoft/`, etc.) |
168
- | **Groq** | Removes `-versatile` and numeric suffixes (`-32768`) |
169
- | **Cerebras** | Normalizes `llama3.1` → `llama-3.1`, adds `instruct` suffix |
170
- | **Mistral** | Strips `-latest` suffix |
171
- | **Ollama** | Converts `model:tag` → `model-tag` |
172
-
173
- **Debug missing scores:** Check `~/.pi/modelmatch.log` to see which models matched/didn't match and what normalization was applied.
174
-
175
- ### 🔄 Free/Paid Model Toggling
176
-
177
- Providers have different pricing models. pi-free handles them all:
178
-
179
- - **Free-only by default** — Shows only zero-cost models initially
180
- - **Per-provider toggles** — Run `/toggle-{provider}` to switch between "free only" vs "all models"
181
- - **Persists across sessions** — Your preference is saved to `~/.pi/free.json`
182
- - **Instant updates** — Changes apply immediately; no Pi restart needed
183
-
184
- **Provider types:**
185
-
186
- - ✅ **Free providers** (OpenCode, Kilo, Cline) — Toggle between free-only vs paid models
187
- - 🔄 **Freemium** (NVIDIA, Ollama) — Free tier with limits, toggle shows all
188
- - 🔧 **Dynamic API** (Mistral, Groq, Cerebras, xAI) — Fetched when API key configured, toggle filters the list
189
-
190
- ### 🔐 OAuth + API Key Handling
191
-
192
- Authentication is handled automatically:
193
-
194
- - **OAuth flows** — `/login kilo` and `/login cline` open your browser, wait for authorization, and complete automatically
195
- - **Multiple auth sources** — API keys read from `~/.pi/free.json`, environment variables, or standard Pi auth files (`~/.pi/agent/auth.json`)
196
- - **Smart fallbacks** — New env var names (e.g., `CF_API_TOKEN`) with legacy support (`CLOUDFLARE_API_TOKEN`)
197
-
198
- ---
199
-
200
- ## Using Free Models (No Setup Required)
201
-
202
- ### OpenCode
203
-
204
- Works immediately with zero setup:
205
-
206
- 1. Press `Ctrl+L`
207
- 2. Search for `opencode/`
208
- 3. Pick any model (e.g., `opencode/big-pickle`)
209
- 4. Start chatting
210
-
211
- No account, no API key, no OAuth. Run `/toggle-opencode` to switch between free and paid OpenCode models.
212
-
213
- ### Kilo (free models, more after login)
214
-
215
- Kilo shows free models immediately. To unlock all models, authenticate with Kilo's free OAuth:
216
-
217
- ```
218
- /login kilo
219
- ```
220
-
221
- This command will:
222
-
223
- 1. Open your browser to Kilo's authorization page
224
- 2. Show a device code in Pi's UI
225
- 3. Wait for you to authorize in the browser
226
- 4. Automatically complete login once approved
227
-
228
- - No credit card required
229
- - Free tier: 200 requests/hour
230
- - After login, run `/toggle-kilo` to switch between free-only and all models
231
-
232
- ### Cline (free account)
233
-
234
- Cline models appear immediately in the model picker. To use them, authenticate with Cline's free account:
235
-
236
- ```
237
- /login cline
238
- ```
239
-
240
- This command will:
241
-
242
- 1. Open your browser to Cline's sign-in page
243
- 2. Wait for you to complete sign-in
244
- 3. Automatically complete login once approved
245
-
246
- - Free account required (no credit card)
247
- - Uses local ports 48801-48811 for OAuth callback
248
-
249
- ---
250
-
251
- ## Providers That Need Authentication
252
-
253
- Some providers require a free account or API key to access their free tiers.
254
-
255
- ---
256
-
257
- ### 🆓 Free Providers
258
-
259
- ### OpenRouter (free models available)
260
-
261
- Get a free API key at [openrouter.ai/keys](https://openrouter.ai/keys), then either:
262
-
263
- **Option A: Environment variable**
264
-
265
- ```bash
266
- export OPENROUTER_API_KEY="sk-or-v1-..."
267
- ```
268
-
269
- **Option B: Config file** (`~/.pi/free.json`)
270
-
271
- ```json
272
- {
273
- "openrouter_api_key": "sk-or-v1-..."
274
- }
275
- ```
276
-
277
- Then use `/toggle-openrouter` to switch between free-only and all models.
278
-
279
- ### NVIDIA NIM (Free Credits System)
280
-
281
- NVIDIA provides **free monthly credits** (1000 requests/month) at [build.nvidia.com](https://build.nvidia.com).
282
-
283
- **Important:** Models have different "costs" per token:
284
-
285
- - **Zero-cost models**: Don't consume your credit balance (shown by default)
286
- - **Credit-costing models**: Consume credits faster (hidden by default)
287
-
288
- Get your API key and optionally enable all models:
289
-
290
- **Option A: Show only free models (default)**
291
-
292
- ```bash
293
- export NVIDIA_API_KEY="nvapi-..."
294
- ```
295
-
296
- Uses only zero-cost models → your 1000 credits last the full month
297
-
298
- **Option B: Show all models (uses credits faster)**
299
-
300
- ```bash
301
- export NVIDIA_API_KEY="nvapi-..."
302
- export NVIDIA_SHOW_PAID=true
303
- ```
304
-
305
- Or in `~/.pi/free.json`:
306
-
307
- ```json
308
- {
309
- "nvidia_api_key": "nvapi-...",
310
- "nvidia_show_paid": true
311
- }
312
- ```
313
-
314
- Toggle anytime with `/toggle-nvidia`
315
-
316
- **Models available:** Llama 4/3.x, Mistral Small 3.1, DeepSeek R1, Gemma 4, Kimi K2.5/2.6, Qwen 3/2.5, OpenAI GPT-OSS, and more.
317
-
318
- ### Ollama Cloud
319
-
320
- Get an API key from [ollama.com/settings/keys](https://ollama.com/settings/keys), then:
321
-
322
- **Option A: Environment variable**
323
-
324
- ```bash
325
- export OLLAMA_API_KEY="..."
326
- export OLLAMA_SHOW_PAID=true
327
- ```
328
-
329
- **Option B: Config file** (`~/.pi/free.json`)
330
-
331
- ```json
332
- {
333
- "ollama_api_key": "YOUR_KEY",
334
- "ollama_show_paid": true
335
- }
336
- ```
337
-
338
- **Note:** Ollama requires `OLLAMA_SHOW_PAID=true` because they have usage limits on their cloud API.
339
-
340
- Free tier resets every 5 hours + 7 days.
341
-
342
- ### Mistral (free API key)
343
-
344
- Add API key to `~/.pi/free.json` or environment variables:
345
-
346
- ```bash
347
- export MISTRAL_API_KEY="..."
348
- ```
349
-
350
- ---
351
-
352
- ## Slash Commands
353
-
354
- Each provider has toggle commands to switch between free and all models:
355
-
356
- | Command | Action |
357
- | --------------------- | -------------------------------------------------------- |
358
- | `/toggle-opencode` | Toggle between free/all OpenCode models |
359
- | `/toggle-kilo` | Toggle between free/all Kilo models |
360
- | `/toggle-openrouter` | Toggle between free/all OpenRouter models |
361
- | `/toggle-cline` | Toggle between free/all Cline models |
362
- | `/toggle-nvidia` | Toggle between free/all NVIDIA models |
363
- | `/toggle-ollama` | Toggle between free/all Ollama Cloud models |
364
- | `/toggle-mistral` | Toggle between free/all Mistral models (🔧 dynamic) |
365
- | `/toggle-groq` | Toggle between free/all Groq models (🔧 dynamic) |
366
- | `/toggle-cerebras` | Toggle between free/all Cerebras models (🔧 dynamic) |
367
- | `/toggle-xai` | Toggle between free/all xAI models (🔧 dynamic) |
368
- | `/toggle-huggingface` | Toggle between free/all Hugging Face models (🔧 dynamic) |
369
-
370
- /toggle-zenmux # Toggle ZenMux (💳 paid - needs API key with credits)
371
- /toggle-crofai # Toggle CrofAI (💳 paid - needs API key with credits)
372
-
373
- **The toggle command:**
374
-
375
- - **For ✅ free providers**: Switches between showing only free models vs. all available models (including paid)
376
- - **For 🔄 freemium providers**: Shows all models by default; toggle switches between filtered and full list
377
- - **For 🔧 dynamic API providers**: Filters the model list when you have an API key configured
378
- - **Persists your preference** to `~/.pi/free.json` for next startup
379
- - Shows a notification: "opencode: showing free models" or "opencode: showing all models"
380
-
381
- ### Probe Commands (Health Check)
382
-
383
- Test models for 404/403 errors and auto-hide broken ones:
384
-
385
- | Command | What it does |
386
- | --------------- | ----------------------------------------------------------- |
387
- | `/probe-nvidia` | Test all NVIDIA models, auto-hide 404s in `~/.pi/free.json` |
388
- | `/probe-ollama` | Test all Ollama models, auto-hide 403s in `~/.pi/free.json` |
389
-
390
- **How it works:**
391
-
392
- 1. Sends a minimal test request to every model
393
- 2. Identifies broken models (404/403 responses)
394
- 3. **Auto-hides** broken models in your config (provider-scoped: `"ollama/kimi-k2.6"`)
395
- 4. Re-registers the provider so broken models disappear immediately
396
- 5. Hidden models persist across Pi restarts
397
-
398
- Use these when you see models that appear in the picker but fail when you try to use them.
399
-
400
- ---
401
-
402
- ## Configuration
403
-
404
- Create `~/.pi/free.json` in your home directory:
405
-
406
- ```json
407
- {
408
- "openrouter_api_key": "YOUR_OPENROUTER_KEY",
409
- "nvidia_api_key": "YOUR_NVIDIA_KEY",
410
- "mistral_api_key": "YOUR_MISTRAL_KEY",
411
- "opencode_api_key": "YOUR_OPENCODE_KEY",
412
- "ollama_api_key": "YOUR_OLLAMA_KEY",
413
- "ollama_show_paid": true,
414
- "hidden_models": ["model-id-to-hide"]
415
- }
416
- ```
417
-
418
- Or use environment variables (same names, uppercase):
419
-
420
- ```bash
421
- export OPENROUTER_API_KEY="..."
422
- export NVIDIA_API_KEY="..."
423
- ```
424
-
425
- ---
426
-
427
- ## Logging & Debugging
428
-
429
- pi-free writes extension logs to:
430
-
431
- - **Windows:** `%USERPROFILE%\.pi\free.log`
432
- - **Linux/macOS:** `~/.pi/free.log`
433
-
434
- If the extension fails to read `~/.pi/free.json`, check this log first — config parse errors are written here.
435
-
436
- ```bash
437
- # Console log verbosity (default: error)
438
- LOG_LEVEL=debug
439
-
440
- # File log verbosity (default: debug)
441
- PI_FREE_LOG_LEVEL=debug
442
-
443
- # Custom log path (optional)
444
- PI_FREE_LOG_PATH=/tmp/pi-free.log
445
-
446
- # Disable file logging
447
- PI_FREE_FILE_LOG=false
448
- ```
449
-
450
- ### Model Matching Debug Log
451
-
452
- To diagnose why some models don't show Coding Index scores, pi-free writes detailed matching diagnostics to:
453
-
454
- - **Windows:** `%USERPROFILE%\.pi\modelmatch.log`
455
- - **Linux/macOS:** `~/.pi/modelmatch.log`
456
-
457
- **Log format:**
458
-
459
- ```
460
- timestamp|provider|modelId|modelName|action|strategy|normalizedId|matchKey|codingIndex|details
461
- ```
462
-
463
- **Example entries:**
464
-
465
- ```
466
- 2026-04-26T10:30:00Z|nvidia|meta/llama-3.1-405b-instruct|Llama 3.1 405B|match|provider-normalized:strip-nvidia-prefix|llama-3.1-405b-instruct|llama-3.1-instruct-405b|52.3|
467
- 2026-04-26T10:30:01Z|groq|llama-3.1-70b-versatile|Llama 3.1 70B Versatile|match|strip-groq-versatile|llama-3.1-70b|llama-3.1-instruct-70b|48.5|
468
- 2026-04-26T10:30:02Z|cloudflare|@cf/meta/llama-3.1-70b|Llama 3.1 70B|miss|all-strategies-failed|llama-3.1-70b|||
469
- ```
470
-
471
- **Common mismatch patterns:**
472
-
473
- - `miss` + `all-strategies-failed` = Model not in benchmark database or ID format not recognized
474
- - Check `normalizedId` column to see what the lookup tried against
475
-
476
- **View the log:**
477
-
478
- ```bash
479
- # Pretty-print with column alignment
480
- cat ~/.pi/modelmatch.log | column -t -s '|'
481
-
482
- # See only misses (models without CI scores)
483
- grep '|miss|' ~/.pi/modelmatch.log
484
-
485
- # See stats for specific provider
486
- grep '|nvidia|' ~/.pi/modelmatch.log | grep -c '|match|'
487
- ```
488
-
489
- ---
490
-
491
- ## License
492
-
493
- MIT — See [LICENSE](LICENSE)
494
-
495
- **Questions?** [Open an issue](https://github.com/apmantza/pi-free/issues)
1
+ # pi-free-providers
2
+
3
+ <p align="center">
4
+ <img src="banner.png" alt="pi-free" width="100%" max-width="900">
5
+ </p>
6
+
7
+ Free and paid AI model providers for [Pi](https://pi.dev). Access **free and paid models** from multiple providers in one install.
8
+
9
+ ---
10
+
11
+ ## What does pi-free do
12
+
13
+ **pi-free is a Pi extension that unlocks free and paid AI models from multiple providers.**
14
+
15
+ When you install pi-free, it:
16
+
17
+ 1. **Registers free-tier providers** with Pi's model picker — Kilo (free), Cline (free), NVIDIA (freemium), ZenMux (paid), CrofAI (paid), Ollama Cloud (freemium), and more
18
+
19
+ 2. **Fetches models dynamically** from provider APIs — NVIDIA NIM, ZenMux, CrofAI, and Pi's built-in providers (Mistral, Groq, Cerebras, xAI, Hugging Face, OpenRouter) when API keys are configured
20
+
21
+ 3. **Filters to show only free models by default** for providers that expose pricing — You see only the models that cost $0 to use. Paid models are hidden until you explicitly toggle them on.
22
+
23
+ 4. **Provides per-provider toggle commands** — Run `/toggle-{provider}` (e.g., `/toggle-kilo`, `/toggle-opencode`) to switch between free-only mode and showing all models including paid ones. Changes apply immediately and your preference is saved for the next Pi restart.
24
+
25
+ 5. **Handles authentication for you** — OAuth flows (Kilo, Cline) open your browser automatically; API keys are read from `~/.pi/free.json` or environment variables
26
+
27
+ 6. **Adds Coding Index scores** — Model names include a coding benchmark score (CI: 45.2) to help you pick capable coding models at a glance
28
+
29
+ 7. **Persists your preferences** — Your toggle choices (free vs all models) are saved to `~/.pi/free.json` and remembered across Pi restarts
30
+
31
+ ---
32
+
33
+ ## How to use
34
+
35
+ ### 1. Install the extension
36
+
37
+ ```bash
38
+ pi install git:github.com/apmantza/pi-free
39
+ ```
40
+
41
+ ### 2. Open the model picker
42
+
43
+ Start Pi and press `Ctrl+L` to open the model picker.
44
+
45
+ Free models are shown by default — look for the provider prefixes:
46
+
47
+ **✅ Free Models (no payment required):**
48
+
49
+ - `opencode/` — OpenCode models (no setup required; toggle with `/toggle-opencode`)
50
+ - `kilo/` — Kilo models (free models available immediately, more after `/login kilo`)
51
+ - `openrouter/` — OpenRouter models (free account required)
52
+ - `cline/` — Cline models (run `/login cline` to use)
53
+
54
+ **🔄 Freemium (free tier with limits, then paid):**
55
+
56
+ - `nvidia/` — NVIDIA NIM models (1,000 free requests/month, then credits)
57
+ - `ollama-cloud/` — Ollama Cloud models (usage-based free tier, resets every 5 hours + 7 days)
58
+ **💳 Paid Providers (API key with credits required):**
59
+
60
+ - `zenmux/` — ZenMux AI gateway (200+ models from OpenAI, Anthropic, Google, etc.)
61
+ - `crofai/` — CrofAI OpenAI-compatible API (streaming, reasoning models)
62
+
63
+ > **Note:** Paid providers may occasionally offer free models or promotional credits. The `isFreeModel` helper automatically detects free models based on provider pricing data or model names containing "free". For providers that don't expose pricing (like CrofAI), only models with "free" in their names are marked as free.
64
+
65
+ **🔧 Dynamic API Providers (fetched when API key configured):**
66
+
67
+ - `mistral/` — Mistral models (when `MISTRAL_API_KEY` set)
68
+ - `groq/` — Groq models (when `GROQ_API_KEY` set)
69
+ - `cerebras/` — Cerebras models (when `CEREBRAS_API_KEY` set)
70
+ - `xai/` — xAI models (when `XAI_API_KEY` set)
71
+ - `huggingface/` — Hugging Face models (when `HF_TOKEN` set)
72
+
73
+ **Note:** Fireworks is now a [built-in Pi provider](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/CHANGELOG.md#0681---2026-04-22) — no extension needed. Set `FIREWORKS_API_KEY` to use it directly.
74
+
75
+ ### 3. Toggle between free and paid models
76
+
77
+ Want to see paid models too? Run the toggle command for your provider:
78
+
79
+ ```
80
+ /toggle-opencode # Toggle OpenCode (✅ offers free models)
81
+ /toggle-kilo # Toggle Kilo (✅ offers free models)
82
+ /toggle-openrouter # Toggle OpenRouter (✅ offers free models)
83
+ /toggle-cline # Toggle Cline (✅ offers free models)
84
+ /toggle-nvidia # Toggle NVIDIA (🔄 freemium)
85
+ /toggle-ollama # Toggle Ollama Cloud (🔄 freemium)
86
+ /toggle-mistral # Toggle Mistral (🔧 dynamic - needs API key)
87
+ /toggle-groq # Toggle Groq (🔧 dynamic - needs API key)
88
+ /toggle-cerebras # Toggle Cerebras (🔧 dynamic - needs API key)
89
+ /toggle-xai # Toggle xAI (🔧 dynamic - needs API key)
90
+ /toggle-huggingface # Toggle Hugging Face (🔧 dynamic - needs HF_TOKEN)
91
+ /toggle-zenmux # Toggle ZenMux (💳 paid - needs API key with credits)
92
+ /toggle-crofai # Toggle CrofAI (💳 paid - needs API key with credits)
93
+ ```
94
+
95
+ **Notes:**
96
+
97
+ - **Toggle commands are mainly for ✅ and 🔄 providers** — to switch between "free models only" vs "show paid models too"
98
+ - **🔧 Dynamic providers** show all fetched models by default — the toggle filters the list when you have an API key configured
99
+ - **Freemium providers** show all models by default; you manage your usage limits via their dashboards
100
+
101
+ You'll see a notification like: `opencode: showing free models` or `opencode: showing all models`
102
+
103
+ **Note:** Built-in provider toggles such as OpenCode and OpenRouter update in the current session — no restart needed.
104
+
105
+ ### 4. Add API keys for more providers (optional)
106
+
107
+ Some providers require a free account or API key.
108
+
109
+ **The first time you run Pi after installing this extension, a config file is automatically created:**
110
+
111
+ - **Linux/Mac:** `~/.pi/free.json`
112
+ - **Windows:** `%USERPROFILE%\.pi\free.json`
113
+
114
+ Add your API keys to this file:
115
+
116
+ ```json
117
+ {
118
+ "openrouter_api_key": "sk-or-v1-...",
119
+ "nvidia_api_key": "nvapi-...",
120
+ "ollama_api_key": "...",
121
+ "mistral_api_key": "...",
122
+ "modal_api_key": "sk-modal-..."
123
+ }
124
+ ```
125
+
126
+ Or set environment variables instead (same names, uppercase: `OPENROUTER_API_KEY`, `NVIDIA_API_KEY`, etc.)
127
+
128
+ If `~/.pi/free.json` contains invalid JSON, pi-free now logs the parse error to `~/.pi/free.log` so you can fix the file quickly.
129
+
130
+ See the [Providers That Need Authentication](#providers-that-need-authentication) section below for detailed setup instructions per provider.
131
+
132
+ ### 5. Quick commands reference
133
+
134
+ | Command | What it does |
135
+ | -------------------- | --------------------------------------------------------- |
136
+ | `/toggle-{provider}` | Switch between free-only and all models for that provider |
137
+ | `/free-providers` | Show free/paid model counts for all providers |
138
+ | `/login kilo` | Start OAuth flow for Kilo |
139
+ | `/login cline` | Start OAuth flow for Cline |
140
+ | `/logout kilo` | Clear Kilo OAuth credentials |
141
+ | `/logout cline` | Clear Cline OAuth credentials |
142
+
143
+ ---
144
+
145
+ ## Features
146
+
147
+ ### 🔍 NVIDIA: Pre-Filtering + 404 Detection
148
+
149
+ NVIDIA's API lists 130+ models, but 57+ return 404 "Function not found" when you try to use them. pi-free solves this:
150
+
151
+ - **57 known 404s hard-filtered** — Discontinued models (`dbrx-instruct`, `codellama-70b`), embedding models mislabeled as chat-capable (`nv-embed-*`), and stale catalog entries are silently excluded
152
+ - **Auto-discovery from NVIDIA's API** — Queries `integrate.api.nvidia.com/v1/models` directly for the ground-truth list
153
+ - **`/probe-nvidia` command** — On-demand health check: tests every model with a minimal request, auto-hides new 404s, and re-registers immediately
154
+
155
+ ### 🎯 Coding Index (CI) Scores
156
+
157
+ Every model shows a **Coding Index score** (e.g., `CI: 52.3`) in the model picker:
158
+
159
+ - **Benchmark-based** — Scores derived from Artificial Analysis coding benchmarks (HumanEval, MBPP, etc.)
160
+ - **Quality indicator** — Higher scores = better coding performance
161
+ - **All providers** — Applied to every model from every provider (NVIDIA, Mistral, Groq, etc.)
162
+
163
+ **Missing CI scores?** Provider model IDs often don't match benchmark database keys exactly. pi-free applies provider-specific normalization to improve matching:
164
+
165
+ | Provider | Normalization Applied |
166
+ | ------------ | ------------------------------------------------------------------ |
167
+ | **NVIDIA** | Strips vendor prefixes (`meta/`, `mistralai/`, `microsoft/`, etc.) |
168
+ | **Groq** | Removes `-versatile` and numeric suffixes (`-32768`) |
169
+ | **Cerebras** | Normalizes `llama3.1` → `llama-3.1`, adds `instruct` suffix |
170
+ | **Mistral** | Strips `-latest` suffix |
171
+ | **Ollama** | Converts `model:tag` → `model-tag` |
172
+
173
+ **Debug missing scores:** Check `~/.pi/modelmatch.log` to see which models matched/didn't match and what normalization was applied.
174
+
175
+ ### 🔄 Free/Paid Model Toggling
176
+
177
+ Providers have different pricing models. pi-free handles them all:
178
+
179
+ - **Free-only by default** — Shows only zero-cost models initially
180
+ - **Per-provider toggles** — Run `/toggle-{provider}` to switch between "free only" vs "all models"
181
+ - **Persists across sessions** — Your preference is saved to `~/.pi/free.json`
182
+ - **Instant updates** — Changes apply immediately; no Pi restart needed
183
+
184
+ **Provider types:**
185
+
186
+ - ✅ **Free providers** (OpenCode, Kilo, Cline) — Toggle between free-only vs paid models
187
+ - 🔄 **Freemium** (NVIDIA, Ollama) — Free tier with limits, toggle shows all
188
+ - 🔧 **Dynamic API** (Mistral, Groq, Cerebras, xAI) — Fetched when API key configured, toggle filters the list
189
+
190
+ ### 🔐 OAuth + API Key Handling
191
+
192
+ Authentication is handled automatically:
193
+
194
+ - **OAuth flows** — `/login kilo` and `/login cline` open your browser, wait for authorization, and complete automatically
195
+ - **Multiple auth sources** — API keys read from `~/.pi/free.json`, environment variables, or standard Pi auth files (`~/.pi/agent/auth.json`)
196
+ - **Smart fallbacks** — New env var names (e.g., `CF_API_TOKEN`) with legacy support (`CLOUDFLARE_API_TOKEN`)
197
+
198
+ ---
199
+
200
+ ## Using Free Models (No Setup Required)
201
+
202
+ ### OpenCode
203
+
204
+ Works immediately with zero setup:
205
+
206
+ 1. Press `Ctrl+L`
207
+ 2. Search for `opencode/`
208
+ 3. Pick any model (e.g., `opencode/big-pickle`)
209
+ 4. Start chatting
210
+
211
+ No account, no API key, no OAuth. Run `/toggle-opencode` to switch between free and paid OpenCode models.
212
+
213
+ ### Kilo (free models, more after login)
214
+
215
+ Kilo shows free models immediately. To unlock all models, authenticate with Kilo's free OAuth:
216
+
217
+ ```
218
+ /login kilo
219
+ ```
220
+
221
+ This command will:
222
+
223
+ 1. Open your browser to Kilo's authorization page
224
+ 2. Show a device code in Pi's UI
225
+ 3. Wait for you to authorize in the browser
226
+ 4. Automatically complete login once approved
227
+
228
+ - No credit card required
229
+ - Free tier: 200 requests/hour
230
+ - After login, run `/toggle-kilo` to switch between free-only and all models
231
+
232
+ ### Cline (free account)
233
+
234
+ Cline models appear immediately in the model picker. To use them, authenticate with Cline's free account:
235
+
236
+ ```
237
+ /login cline
238
+ ```
239
+
240
+ This command will:
241
+
242
+ 1. Open your browser to Cline's sign-in page
243
+ 2. Wait for you to complete sign-in
244
+ 3. Automatically complete login once approved
245
+
246
+ - Free account required (no credit card)
247
+ - Uses local ports 48801-48811 for OAuth callback
248
+
249
+ ---
250
+
251
+ ## Providers That Need Authentication
252
+
253
+ Some providers require a free account or API key to access their free tiers.
254
+
255
+ ---
256
+
257
+ ### 🆓 Free Providers
258
+
259
+ ### OpenRouter (free models available)
260
+
261
+ Get a free API key at [openrouter.ai/keys](https://openrouter.ai/keys), then either:
262
+
263
+ **Option A: Environment variable**
264
+
265
+ ```bash
266
+ export OPENROUTER_API_KEY="sk-or-v1-..."
267
+ ```
268
+
269
+ **Option B: Config file** (`~/.pi/free.json`)
270
+
271
+ ```json
272
+ {
273
+ "openrouter_api_key": "sk-or-v1-..."
274
+ }
275
+ ```
276
+
277
+ Then use `/toggle-openrouter` to switch between free-only and all models.
278
+
279
+ ### NVIDIA NIM (Free Credits System)
280
+
281
+ NVIDIA provides **free monthly credits** (1000 requests/month) at [build.nvidia.com](https://build.nvidia.com).
282
+
283
+ **Important:** Models have different "costs" per token:
284
+
285
+ - **Zero-cost models**: Don't consume your credit balance (shown by default)
286
+ - **Credit-costing models**: Consume credits faster (hidden by default)
287
+
288
+ Get your API key and optionally enable all models:
289
+
290
+ **Option A: Show only free models (default)**
291
+
292
+ ```bash
293
+ export NVIDIA_API_KEY="nvapi-..."
294
+ ```
295
+
296
+ Uses only zero-cost models → your 1000 credits last the full month
297
+
298
+ **Option B: Show all models (uses credits faster)**
299
+
300
+ ```bash
301
+ export NVIDIA_API_KEY="nvapi-..."
302
+ export NVIDIA_SHOW_PAID=true
303
+ ```
304
+
305
+ Or in `~/.pi/free.json`:
306
+
307
+ ```json
308
+ {
309
+ "nvidia_api_key": "nvapi-...",
310
+ "nvidia_show_paid": true
311
+ }
312
+ ```
313
+
314
+ Toggle anytime with `/toggle-nvidia`
315
+
316
+ **Models available:** Llama 4/3.x, Mistral Small 3.1, DeepSeek R1, Gemma 4, Kimi K2.5/2.6, Qwen 3/2.5, OpenAI GPT-OSS, and more.
317
+
318
+ ### Ollama Cloud
319
+
320
+ Get an API key from [ollama.com/settings/keys](https://ollama.com/settings/keys), then:
321
+
322
+ **Option A: Environment variable**
323
+
324
+ ```bash
325
+ export OLLAMA_API_KEY="..."
326
+ export OLLAMA_SHOW_PAID=true
327
+ ```
328
+
329
+ **Option B: Config file** (`~/.pi/free.json`)
330
+
331
+ ```json
332
+ {
333
+ "ollama_api_key": "YOUR_KEY",
334
+ "ollama_show_paid": true
335
+ }
336
+ ```
337
+
338
+ **Note:** Ollama requires `OLLAMA_SHOW_PAID=true` because they have usage limits on their cloud API.
339
+
340
+ Free tier resets every 5 hours + 7 days.
341
+
342
+ ### Mistral (free API key)
343
+
344
+ Add API key to `~/.pi/free.json` or environment variables:
345
+
346
+ ```bash
347
+ export MISTRAL_API_KEY="..."
348
+ ```
349
+
350
+ ---
351
+
352
+ ## Slash Commands
353
+
354
+ Each provider has toggle commands to switch between free and all models:
355
+
356
+ | Command | Action |
357
+ | --------------------- | -------------------------------------------------------- |
358
+ | `/toggle-opencode` | Toggle between free/all OpenCode models |
359
+ | `/toggle-kilo` | Toggle between free/all Kilo models |
360
+ | `/toggle-openrouter` | Toggle between free/all OpenRouter models |
361
+ | `/toggle-cline` | Toggle between free/all Cline models |
362
+ | `/toggle-nvidia` | Toggle between free/all NVIDIA models |
363
+ | `/toggle-ollama` | Toggle between free/all Ollama Cloud models |
364
+ | `/toggle-mistral` | Toggle between free/all Mistral models (🔧 dynamic) |
365
+ | `/toggle-groq` | Toggle between free/all Groq models (🔧 dynamic) |
366
+ | `/toggle-cerebras` | Toggle between free/all Cerebras models (🔧 dynamic) |
367
+ | `/toggle-xai` | Toggle between free/all xAI models (🔧 dynamic) |
368
+ | `/toggle-huggingface` | Toggle between free/all Hugging Face models (🔧 dynamic) |
369
+
370
+ /toggle-zenmux # Toggle ZenMux (💳 paid - needs API key with credits)
371
+ /toggle-crofai # Toggle CrofAI (💳 paid - needs API key with credits)
372
+
373
+ **The toggle command:**
374
+
375
+ - **For ✅ free providers**: Switches between showing only free models vs. all available models (including paid)
376
+ - **For 🔄 freemium providers**: Shows all models by default; toggle switches between filtered and full list
377
+ - **For 🔧 dynamic API providers**: Filters the model list when you have an API key configured
378
+ - **Persists your preference** to `~/.pi/free.json` for next startup
379
+ - Shows a notification: "opencode: showing free models" or "opencode: showing all models"
380
+
381
+ ### Probe Commands (Health Check)
382
+
383
+ Test models for 404/403 errors and auto-hide broken ones:
384
+
385
+ | Command | What it does |
386
+ | --------------- | ----------------------------------------------------------- |
387
+ | `/probe-nvidia` | Test all NVIDIA models, auto-hide 404s in `~/.pi/free.json` |
388
+ | `/probe-ollama` | Test all Ollama models, auto-hide 403s in `~/.pi/free.json` |
389
+
390
+ **How it works:**
391
+
392
+ 1. Sends a minimal test request to every model
393
+ 2. Identifies broken models (404/403 responses)
394
+ 3. **Auto-hides** broken models in your config (provider-scoped: `"ollama/kimi-k2.6"`)
395
+ 4. Re-registers the provider so broken models disappear immediately
396
+ 5. Hidden models persist across Pi restarts
397
+
398
+ Use these when you see models that appear in the picker but fail when you try to use them.
399
+
400
+ ---
401
+
402
+ ## Configuration
403
+
404
+ Create `~/.pi/free.json` in your home directory:
405
+
406
+ ```json
407
+ {
408
+ "openrouter_api_key": "YOUR_OPENROUTER_KEY",
409
+ "nvidia_api_key": "YOUR_NVIDIA_KEY",
410
+ "mistral_api_key": "YOUR_MISTRAL_KEY",
411
+ "opencode_api_key": "YOUR_OPENCODE_KEY",
412
+ "ollama_api_key": "YOUR_OLLAMA_KEY",
413
+ "ollama_show_paid": true,
414
+ "hidden_models": ["model-id-to-hide"]
415
+ }
416
+ ```
417
+
418
+ Or use environment variables (same names, uppercase):
419
+
420
+ ```bash
421
+ export OPENROUTER_API_KEY="..."
422
+ export NVIDIA_API_KEY="..."
423
+ ```
424
+
425
+ ---
426
+
427
+ ## Logging & Debugging
428
+
429
+ pi-free writes extension logs to:
430
+
431
+ - **Windows:** `%USERPROFILE%\.pi\free.log`
432
+ - **Linux/macOS:** `~/.pi/free.log`
433
+
434
+ If the extension fails to read `~/.pi/free.json`, check this log first — config parse errors are written here.
435
+
436
+ ```bash
437
+ # Console log verbosity (default: error)
438
+ LOG_LEVEL=debug
439
+
440
+ # File log verbosity (default: debug)
441
+ PI_FREE_LOG_LEVEL=debug
442
+
443
+ # Custom log path (optional)
444
+ PI_FREE_LOG_PATH=/tmp/pi-free.log
445
+
446
+ # Disable file logging
447
+ PI_FREE_FILE_LOG=false
448
+ ```
449
+
450
+ ### Model Matching Debug Log
451
+
452
+ To diagnose why some models don't show Coding Index scores, pi-free writes detailed matching diagnostics to:
453
+
454
+ - **Windows:** `%USERPROFILE%\.pi\modelmatch.log`
455
+ - **Linux/macOS:** `~/.pi/modelmatch.log`
456
+
457
+ **Log format:**
458
+
459
+ ```
460
+ timestamp|provider|modelId|modelName|action|strategy|normalizedId|matchKey|codingIndex|details
461
+ ```
462
+
463
+ **Example entries:**
464
+
465
+ ```
466
+ 2026-04-26T10:30:00Z|nvidia|meta/llama-3.1-405b-instruct|Llama 3.1 405B|match|provider-normalized:strip-nvidia-prefix|llama-3.1-405b-instruct|llama-3.1-instruct-405b|52.3|
467
+ 2026-04-26T10:30:01Z|groq|llama-3.1-70b-versatile|Llama 3.1 70B Versatile|match|strip-groq-versatile|llama-3.1-70b|llama-3.1-instruct-70b|48.5|
468
+ 2026-04-26T10:30:02Z|cloudflare|@cf/meta/llama-3.1-70b|Llama 3.1 70B|miss|all-strategies-failed|llama-3.1-70b|||
469
+ ```
470
+
471
+ **Common mismatch patterns:**
472
+
473
+ - `miss` + `all-strategies-failed` = Model not in benchmark database or ID format not recognized
474
+ - Check `normalizedId` column to see what the lookup tried against
475
+
476
+ **View the log:**
477
+
478
+ ```bash
479
+ # Pretty-print with column alignment
480
+ cat ~/.pi/modelmatch.log | column -t -s '|'
481
+
482
+ # See only misses (models without CI scores)
483
+ grep '|miss|' ~/.pi/modelmatch.log
484
+
485
+ # See stats for specific provider
486
+ grep '|nvidia|' ~/.pi/modelmatch.log | grep -c '|match|'
487
+ ```
488
+
489
+ ---
490
+
491
+ ## License
492
+
493
+ MIT — See [LICENSE](LICENSE)
494
+
495
+ **Questions?** [Open an issue](https://github.com/apmantza/pi-free/issues)