npm install -g free-coding-models
free-coding-models
💡 Why this tool?
There is a large catalog of free and free-limited coding models (25 providers / 257 live models, generated from sources.js). Which one is fastest right now? Which one is actually stable, versus just lucky on the last ping?
free-coding-models (FCM) answers that by pinging every model in parallel, showing live latency, and computing a live Stability Score (0-100) combining p95 latency, jitter, spike rate and uptime. Average latency alone is misleading: a model that randomly spikes to 6 seconds is not reliable.
Once you pick a model, FCM writes it directly into your coding tool's config and opens the tool, so you go from "which model?" to "coding" in under 10 seconds.
| Surface | What it is | Docs |
|---|
| 🎛️ TUI | The interactive terminal dashboard. The default: live ranking, pick + launch. | docs/tui.md |
| 🌐 Web Dashboard | Browser control center, shareable filtered views, Docker-ready. | docs/web-dashboard.md |
| 🔌 Agent Extensions | OpenCode & Pi plugins: hot-swap models mid-session. | Agent extensions |
| 🔀 Smart Model Router | A local OpenAI-compatible daemon with auto-failover. | docs/router.md |
Other highlights: AI Speed Test benchmarks (real completions, AI Latency + TPS), Smart Recommend (3-question wizard), a Ctrl+P Command Palette, a persistent 24h probe cache shared by every surface, live quota from response headers, real-world telemetry scores, models.dev enrichment with drift detection, and a tier scale based on SWE-bench Verified (S+ ≥ 70% down to C). Details: docs/stability.md.
⚡ Quick Start
① Install (Node.js 18+, no native build, never needs sudo):
npm install -g free-coding-models
free-coding-models --help # prints every flag
② Grab one free API key. One is enough to start; add more later with P inside the app:
③ Launch & paste your key: free-coding-models. First run prompts for keys (Enter skips), models ping in parallel, rows light up green ✅.
④ Pick a model & launch your tool: ↑↓ navigate, Enter to write the model into your tool's config and launch it. Pre-target another tool from the CLI, or cycle live with Z:
free-coding-models --goose --tier S # Goose, pre-filtered to S-tier only
free-coding-models --crush --origin groq # Crush, Groq models only
free-coding-models --fiable # print the single most reliable model and exit
⑤ Go further:
🟢 Providers
25 active providers / 257 live models, sorted by live model count. Top 8:
🧾 What "free" means here: free is a property of the (provider, model) pair, never of the provider as a whole. A row is listed only when that exact model id costs $0 to call through that provider (permanent free tier, :free variant, or free plan), verified live at audit time. The same open-weights model can be free on one host and paid on another - paid siblings are deliberately excluded. Full breakdown and badge legend: docs/providers.md.
📖 Full table, free-tier limits, env vars, tier scale and provider notes: docs/providers.md (generated from sources.js by node scripts/generate-provider-table.mjs, so counts cannot drift). OpenCode Zen's free models are listed there too.
⚠️ Health probes consume provider quota: FCM auto-pauses a provider on 429, backs off exponentially per failing model, and shows a footer chip while a provider rests. Leave a key empty and anonymous liveness probes still work for most providers.
🧩 Your own providers (Ollama, LM Studio, vLLM, private gateways)
Any OpenAI-compatible endpoint can be added to ~/.free-coding-models.json under customProviders (issue #197). Custom models are pinged, scored, filtered, routable through the Smart Router, installable into your coding tools, and visible on the Web Dashboard, exactly like built-in providers:
{
"customProviders": {
"ollama-local": {
"name": "Ollama Local",
"url": "http://localhost:11434/v1/chat/completions",
"quota": "Local, unlimited",
"quotaCode": "free",
"models": [
["qwen3-coder:30b", "Qwen3 Coder 30B", "A", "-", "262k"],
["llama4:70b"]
]
},
"vllm-gpu": {
"url": "https://gpu.internal:8000/v1/chat/completions",
"envVar": "VLLM_API_KEY",
"models": [["deepseek-v4.1", "DeepSeek V4.1", "S", "-", "128k"]]
}
}
}
url (required): any http(s) OpenAI-compatible /chat/completions endpoint.models (required): tuples [id, label?, tier?, sweScore?, ctx?] - only the id is mandatory, the rest gets sensible defaults (tier defaults to B).apiKey / envVar (optional): key inline (supports ${VAR} placeholders) or read from an env var. Omit both for keyless local servers like Ollama or LM Studio - they stay visible and routable without a key.- Provider keys must not collide with built-in providers; colliding entries are ignored. Removing a definition from the file removes the provider at the next restart.
🎛️ The Terminal UI (TUI)
The TUI is the heart of FCM: a live, sortable table of every model with real latency, stability, verdict, and a one-key launch into your coding tool. Sorts are one letter (R rank, S SWE, V verdict, B stability...), filters are T (tier cycle), D (provider cycle), E (visibility cycle), and the essentials are:
| Key | Action |
|---|
↑↓ / Enter | Navigate / launch the selected model |
Z | Cycle target tool (OpenCode → OpenClaw → Crush → Goose → ...) |
F / Y | Favorite a model / toggle pinned favorites mode |
Ctrl+A / Ctrl+U | AI Speed Test on selected model / all visible models |
Q | Smart Recommend (3-question wizard, Top 3 picks) |
Ctrl+P | Command Palette (fuzzy search over every filter, sort and action) |
; | Playground chat with the router |
Shift+P / Ctrl+Shift+P | Re-probe failed rows / probe all models (404/410) |
Space | Expand the selected row (provider, endpoint URL, full model ID) |
Shift+B | Toggle broken-model visibility |
G / P / I / N | Theme / Settings / Help / Reset view |
Ctrl+C | Exit |
Mouse support: click headers to sort, double-click a row to launch, right-click to favorite, scroll to navigate.
Languages
The TUI and Web Dashboard support English (default) and Simplified Chinese (zh-CN). Change Language in Settings; the preference is shared and saved in your local config.
📖 Full key table, mouse reference and workflows: docs/tui.md · Stability score and columns: docs/stability.md
🌐 The Web Dashboard
A real-time browser control center for the same catalog: full filter/sort parity with the TUI, per-row benchmarks, favorites, Smart Recommend, a Router Dashboard, token usage analytics, and shareable URL deep-links (?tier=S+&sort=verdict&origin=groq). Start it with free-coding-models web (port 3333) or free-coding-models --daemon (dashboard + router API on port 19280). Runs headless in Docker (ghcr.io/vava-nessa/free-coding-models).
📖 Modes, Docker, Compose and all env vars (FCM_HOST, FCM_PORT, FCM_WEB_PORT, FCM_ROUTER_TOKEN, FCM_ALLOWED_ORIGINS, FCM_DISCORD_*_WEBHOOK): docs/web-dashboard.md
🔀 The Smart Model Router
A local OpenAI-compatible daemon: point any coding tool at http://localhost:19280/v1 with model fcm (key fcm-local) and FCM routes every request to the best available model in your active set. Adaptive health probes, per-model circuit breakers, family-preserving failover, auto-heal of broken sets, and a Playground chat to try it without configuring a tool.
free-coding-models --daemon-bg # start
free-coding-models --daemon-status # inspect
free-coding-models --daemon-stop # stop
📖 Full guide (probes, circuit breaker, failover, Playground, --sync-set, REST API): docs/router.md
🧪 Router v2 engine (built in)
The router daemon now runs the hardened v2 engine internally: content-validated failover (a 200 with empty or garbage output is a failure and fails over), quota-aware routing with Retry-After pauses, persisted circuit breakers with a DEGRADED warning state, per-request decision traces, an Anthropic /v1/messages endpoint, and "test via router" actions that exercise the real routing chain. Same command, same port, same endpoints - existing setups upgrade by updating the package.
Open the TUI with Shift+V (or the "Router v2" entry in the Web Dashboard) to see the live fallback chain, per-request attempt chains and run pinned-model tests (Ctrl+T). Docs: docs/router-v2.md.
📖 CLI Flags
Flags combine freely in any order. The most common:
| Flag | Effect |
|---|
--best / --premium | Top tiers only / elite preset (S filter + verdict sort) |
--tier <S|A|B|C> | Filter by tier family |
--origin <provider> | Filter by provider (e.g. groq) |
--sort <column> + --asc / --desc | Start sorted by a column (rank, swe, verdict, stability, ...) |
--json | Skip the TUI, print results as JSON (great with jq) |
--fiable | Wait 10s, print the single most reliable model, exit |
--recommend | Open Smart Recommend on startup |
--hide-unconfigured / --show-unconfigured | Control keyless models visibility |
--ping-interval <ms> | Override the ping interval |
--reprobe / --probe-ttl <ms> / --show-broken | Probe cache control |
--check-drift | Diff sources.js vs models.dev, exit 1 on mismatch |
--config-dir <dir> | Custom config location |
--fix-permissions / --yes | Auto-fix config file permissions (chmod 600, NTFS ACLs via icacls on Windows) |
--web | Open the Web Dashboard instead of the TUI |
--daemon / --daemon-bg / --daemon-status / --daemon-stop | Smart Model Router lifecycle |
--sync-set [name] | Auto-populate a router set with the currently best models |
--no-telemetry | Disable anonymous telemetry for this run |
--help / -h | Full in-app help |
Tool launchers (21): --opencode (default), --openclaw, --crush, --goose, --aider, --kilo, --qwen, --openhands, --amp, --pi, --hermes, --continue, --cline, --xcode, --copilot, --forgecode, --zcode, --jcode, --caveman, plus OpenCode Desktop / WebUI variants.
📖 Canonical full flag reference (every flag, verified against the parser): docs/flags.md · Tool-to-config mapping: docs/integrations.md
🔌 Agent Extensions
- OpenCode plugin (
fcm-opencode, beta): /fcm scans and ranks, /fcm 1 switches models, /fcm rescan forces a fresh scan. Install: packages/fcm-opencode/README.md
- Pi extension (
fcm-pi, beta): silent by default, /fcm re-scans and lets you pick, /fcm-list shows a ranked table, error-triggered picker on 4xx/5xx. Install: packages/fcm-pi/README.md
- Shared core (
fcm-agent-core): one scan/rank/cache engine for both adapters, with a cross-tool cache and daemon integration. API: packages/fcm-agent-core/README.md
📋 Contributing
Issues, PRs and new provider integrations are welcome. To add a provider, see the format in sources.js and re-run node scripts/generate-provider-table.mjs so docs/providers.md stays in sync. Latency numbers are real round-trip times from your machine.
→ Development guide · Config reference · Sync-set · Contributors
⚖️ Model Licensing
You own the generated output: the code and text these models produce is yours to use commercially under current provider terms. The licenses below govern the model weights, not your output: Apache 2.0 (Qwen, GPT-OSS, Devstral, Gemma), MIT / permissive (GLM Flash, MiniMax), Modified MIT (Kimi K2), Llama Community License (attribution required), DeepSeek and NVIDIA Nemotron licenses, and hosted-API terms (Gemini, Mistral, OpenRouter-hosted). Verify on the model's official page before making legal decisions; this is a summary, not legal advice.
📊 Telemetry
FCM collects anonymous usage telemetry (app version, tool mode, OS, terminal family, a random install ID). No personal information, API keys, prompts, source code, or file paths ever leave your machine. Disable with --no-telemetry or FREE_CODING_MODELS_TELEMETRY=0.
🛡️ Security & Trust
| Signal | Status |
|---|
| npm Provenance | ✅ Sigstore-signed |
| SBOM | ✅ Attached to every GitHub Release |
| Dependencies | ✅ Small, pure JavaScript (chalk for the TUI; socket.io + UI libs for the dashboard), no native builds |
| Security Policy | ✅ SECURITY.md |
Dependabot + npm audit CI | ✅ Weekly updates, scan on every push |
| License | ✅ MIT |
Keys live locally in ~/.free-coding-models.json (0600) and are only ever sent to the matching provider endpoint. FCM never requires sudo and never executes arbitrary remote code. To report a vulnerability, see SECURITY.md.
Star History
Contributors
Created and maintained by Vanessa Depraute (@vava-nessa), with contributions from @erwinh22, @whit3rabbit, @skylaweber, @PhucTruong-ctrl, @chindris-mihai-alexandru, @serajbaltu, @stgreenb, @MoriDanWork, @fan92rus, @Muhammad95959, @FaintFlower, @lehneres, @ia-S-on, @bangla24bdrang-lab and @Sy57em1.
→ Full credits and highlighted contributions: CONTRIBUTORS.md
📚 More docs
Providers · TUI · Web Dashboard · Router · Flags · Integrations · Stability & columns · Sync-set · Config · Development · Other free AI resources
License
MIT
