You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+78Lines changed: 78 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -466,6 +466,84 @@ When a tool mode is active (via `Z`), models incompatible with that tool are hig
466
466
467
467
---
468
468
469
+
## π Pi Extension — FCM-Pi
470
+
471
+
**FCM-Pi** is a native [Pi coding agent](https://pi.dev) extension that integrates `free-coding-models` directly into your Pi session. It auto-selects the best free model on startup, shows a live animated scan in the Pi status bar, and lets you hot-swap models mid-session.
472
+
473
+
> **Requires**: Pi coding agent (pi.dev) + free-coding-models installed and configured with at least one API key.
474
+
475
+
### Installation
476
+
477
+
Add the extension to your Pi settings (`~/.pi/agent/settings.json`):
Or install directly from the Pi shell once published to npm:
488
+
```bash
489
+
pi install npm:fcm-pi
490
+
```
491
+
492
+
### What it does
493
+
494
+
| Feature | Description |
495
+
|---------|-------------|
496
+
|**Auto-scan on startup**| On every Pi session start, FCM pings ~30 candidate models in parallel and selects the best one automatically |
497
+
|**Animated progress scan**| While scanning, the Pi status bar shows a live magenta spinner with the model + provider being probed and a real-time % progress |
498
+
|**Provider in status bar**| The active model is displayed as `GLM 4.7 (Cerebras) [FCM S+]` so you always know exactly what's running |
499
+
|**10-minute disk cache**| Results are cached to `~/.pi/agent/fcm-cache.json` — subsequent session starts are instant |
500
+
|**Auto-failover**| If a request fails (HTTP 4xx/5xx), FCM auto-triggers a fresh scan and switches to the next best model |
501
+
|**Daemon integration**| If the FCM router daemon is running (`free-coding-models --daemon-bg`), scan results are fetched instantly from its cache |
502
+
503
+
### Scan progress display
504
+
505
+
During `/fcm` or on session start, the Pi footer status shows:
-**Live model name + provider** — shows the last 2 models being probed, scrolling as results come in
515
+
-**Progress %** and counter always visible
516
+
517
+
### Commands
518
+
519
+
| Command | Description |
520
+
|---------|-------------|
521
+
|`/fcm`| Re-scan and pick a model interactively from the top 10 ranked |
522
+
|`/fcm-list`| Display a ranked table of top 20 available models (SWE / Latency / TPS / Provider) |
523
+
|`/fcm-router`| Connect Pi to the local FCM Smart Router daemon (auto-failover across providers) |
524
+
|`/fcm-status`| Show diagnostics: active model, last scan source, daemon state |
525
+
526
+
### Composite ranking
527
+
528
+
Models are ranked using a composite score:
529
+
530
+
| Weight | Metric | Description |
531
+
|--------|--------|-------------|
532
+
|**60%**| SWE-bench score | Coding capability |
533
+
|**20%**| Latency | Network round-trip response time |
534
+
|**10%**| TPS | Token throughput speed |
535
+
|**10%**| Stability | Uptime + success rate |
536
+
537
+
### Context window limits
538
+
539
+
Cerebras free-tier API has a strict **8192 total token limit** (prompt + tools + completion). The FCM catalog reflects this accurately so Pi allocates the right budget and doesn't overflow the context silently.
540
+
541
+
### Full documentation
542
+
543
+
See [`pi-extension/README.md`](./pi-extension/README.md) for the complete architecture diagram, config format, and troubleshooting guide.
-**Pi Extension documentation**: Added a full `## π Pi Extension — FCM-Pi` section to the main `README.md` covering installation, scan progress display, commands, composite ranking, and context window notes.
5
+
-**Rewrote `pi-extension/README.md`**: Complete documentation rewrite covering all current features — animated progress scan, provider-in-status-bar, auto-failover, daemon integration, file structure, and provider-specific notes (Cerebras limits, NVIDIA NIM quota).
Copy file name to clipboardExpand all lines: package.json
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
{
2
2
"name": "free-coding-models",
3
-
"version": "0.5.42",
3
+
"version": "0.5.43",
4
4
"description": "Find the fastest coding LLM models in seconds — ping free models from multiple providers, pick the best one for OpenCode, Cursor, or any AI coding assistant.",
A lightweight JavaScript extension for the **Pi coding agent (pi.dev)** that connects to **free-coding-models**(FCM). It runs round-trip pings and real-answer AI latency benchmarks on your configured free models, and automatically activates the most performant, usable model before your coding session starts.
3
+
A native JavaScript extension for the **[Pi coding agent](https://pi.dev)** that wires **free-coding-models**directly into your Pi session. It pings ~30 candidate models in parallel, benchmarks the top 5, auto-selects the best one on startup, and displays a real-time animated progress scan in the Pi status bar.
4
4
5
5
---
6
6
7
7
## ✨ Features
8
8
9
-
-**Auto-scan on session startup**: Runs a quick scan when Pi boots up, updating status dynamically in the terminal footer.
10
-
-**Smart model selection**: Auto-configures Pi to use the highest-performing model based on a composite score:
-**Magenta Braille spinner** — 10-frame animation at 80ms refresh rate
68
+
-**Yellow phase label** — `Probing` during the ping phase, `Benchmarking` during the AI latency phase
69
+
-**Cyan model + provider** — the last 2 actively probed models scroll in real time
70
+
-**Progress %** and `(completed/total)` counter always shown
71
+
72
+
Once complete, the status bar settles on:
73
+
74
+
```
75
+
✅ GLM 4.7 (Cerebras) [FCM S+] — 340ms
76
+
```
77
+
78
+
---
79
+
80
+
## 🏗️ Architecture & Scan Strategies
52
81
53
82
```
54
83
[Pi Session Starting]
@@ -60,35 +89,116 @@ pi install npm:fcm-pi
60
89
YES NO
61
90
/ \
62
91
[Daemon Scan (~1s)] [Direct Scan (~8-15s)]
63
-
Query cache & stats Ping 30 candidate models
64
-
directly from daemon Benchmark top 5 candidates
92
+
Query cache & stats Ping top 30 models in parallel
93
+
directly from daemon Benchmark top 5 survivors
65
94
\ /
66
95
\ /
67
96
Filter: status === 'up'
68
97
Rank: Compute composite scores
69
-
Select: Write Pi configurations
98
+
Select: Write Pi config + switch session
70
99
│
71
100
▼
72
101
[Pi Session Ready to Code!]
73
102
```
74
103
75
-
-**Daemon Mode**: Checks if the FCM background daemon is active. If so, fetches pre-cached latency and stats in under 1 second.
76
-
-**Direct Mode (Fallback)**: Performs a parallel ping of the top 30 models from the FCM registry, then benchmarks the top 5 smartest models, completing in ~8-15 seconds.
77
-
-**Config Persistence**: Modifies `~/.pi/agent/models.json` and `~/.pi/agent/settings.json` to store provider URLs and default model choices.
104
+
### Daemon Mode (fast path)
105
+
When `free-coding-models --daemon-bg` is running, the extension queries `localhost:19280/api/models` and `/stats` directly. Scan completes in under 1 second using pre-cached latency data.
106
+
107
+
### Direct Mode (fallback)
108
+
If the daemon is not running, the extension:
109
+
1. Loads the FCM model catalog (~191 models across 20 providers)
110
+
2. Filters to models with a configured API key
111
+
3. Sorts by SWE-bench score and takes top 30 candidates
112
+
4. Pings all 30 in parallel (15s timeout each)
113
+
5. Filters to models that returned HTTP 200
114
+
6. Benchmarks top 5 by SWE score (measures real AI output latency + TPS)
115
+
7. Ranks and selects the winner
78
116
79
117
---
80
118
81
119
## ⌨️ Command Reference
82
120
83
-
| Command | Action |
84
-
|---------|--------|
85
-
|`/fcm`| Re-runs diagnostic scan and presents interactive top 10 model list |
86
-
|`/fcm-list`| Renders a styled table of the top 20 available models with SWE/Latency/TPS |
87
-
|`/fcm-router`| Configures Pi to route completions through the FCM Smart Router daemon |
|**10%**| TPS | Tokens per second from AI latency benchmark |
137
+
|**10%**| Stability | Model stability score from FCM ping history (0-100) |
138
+
139
+
---
140
+
141
+
## 🗂️ Config Files Modified
142
+
143
+
| File | What's stored |
144
+
|------|---------------|
145
+
|`~/.pi/agent/models.json`| Provider URL, API key, model ID and capabilities |
146
+
|`~/.pi/agent/settings.json`| Default provider and model selection |
147
+
|`~/.pi/agent/fcm-cache.json`| Last scan results with 10-minute TTL |
148
+
149
+
---
150
+
151
+
## ⚠️ Provider-Specific Notes
152
+
153
+
### Cerebras
154
+
Cerebras free-tier has a **strict 8192 total token limit** (prompt + tools + completion combined). The FCM catalog reflects this accurately — Pi allocates a smaller context budget when using Cerebras models, preventing silent overflow errors.
155
+
156
+
Cerebras also enforces **5 RPM** on the free tier. FCM uses a single ping per model scan (no thinking parameters that trigger double-requests) to stay within quota.
157
+
158
+
### NVIDIA NIM
159
+
NIM has ~40 RPM on the no-credit-card tier. The parallel ping scan may exhaust this temporarily on the first scan; subsequent scans use the cache.
160
+
161
+
---
162
+
163
+
## 🔄 Auto-Failover
164
+
165
+
When the active model returns an HTTP 4xx or 5xx error, FCM automatically:
166
+
167
+
1. Detects the failure via the `agent_end` hook
168
+
2. Notifies you with a banner: `⚠️ Le modèle actif a renvoyé une erreur. Recherche d'une alternative...`
169
+
3. Triggers a fresh full scan
170
+
4. Switches to the next best working model
171
+
5. Shows a confirmation notification
172
+
173
+
This runs silently — you don't need to manually `/fcm` when a model goes down.
174
+
175
+
---
176
+
177
+
## 📁 File Structure
178
+
179
+
```
180
+
pi-extension/
181
+
├── package.json — Extension manifest (fcm-pi)
182
+
├── extensions/
183
+
│ └── index.js — Pi extension entry point (hooks + commands)
184
+
└── lib/
185
+
├── scanner.js — Orchestrator (daemon → direct fallback)
186
+
├── direct-scanner.js — Parallel ping + benchmark with animated progress
├── daemon-client.js — HTTP client for FCM daemon (localhost:19280)
190
+
└── api-keys.js — Loads API keys from FCM config + env vars
191
+
```
89
192
90
193
---
91
194
92
195
## 🧹 Telemetry & Security
93
196
94
-
This extension does not collect or transmit API keys, source code, or personal data. It works entirely offline or connects only to your configured AI providers and local loopback address (`http://localhost:19280`).
197
+
This extension does **not** collect or transmit:
198
+
- API keys
199
+
- Source code or project files
200
+
- Personal data or usage patterns
201
+
202
+
It operates entirely offline or connects only to:
203
+
- Your configured AI provider APIs (Cerebras, Nvidia, Groq, etc.)
204
+
- The local FCM daemon at `http://localhost:19280` (optional)
0 commit comments