free-coding-models

Contributors

_{vava-nessa · erwinh22 · whit3rabbit · skylaweber · PhucTruong-ctrl}

💬 Let's talk about the project on Discord

By Vanessa Depraute

1. Create a free API key (NVIDIA, OpenRouter, Hugging Face, etc.)
2. npm i -g free-coding-models
3. free-coding-models

Find the fastest coding LLM models in seconds
_{Ping free coding models from 20 providers in real-time — pick the best one for OpenCode, OpenClaw, or any AI coding assistant}

Features • Requirements • Installation • Usage • Columns • Stability • Models • OpenCode • OpenClaw • How it works

✨ Features

• 🎯 Coding-focused — Only LLM models optimized for code generation, not chat or vision
• 🌐 Multi-provider — Models from NVIDIA NIM, Groq, Cerebras, SambaNova, OpenRouter, Hugging Face Inference, Replicate, DeepInfra, Fireworks AI, Codestral, Hyperbolic, Scaleway, Google AI, SiliconFlow, Together AI, Cloudflare Workers AI, Perplexity API, Alibaba Cloud (DashScope), ZAI, and iFlow
• ⚙️ Settings screen — Press P to manage provider API keys, enable/disable providers, access FCM Proxy V2 settings, and check/install updates
• 📡 FCM Proxy V2 — Built-in reverse proxy with multi-key rotation, rate-limit failover, and Anthropic wire format translation for Claude Code. Optional always-on background service (launchd/systemd) keeps the proxy running 24/7 — even without the TUI. Dedicated overlay with full status, restart, stop, force-kill, and log viewer.
• 🚀 Parallel pings — All models tested simultaneously via native fetch
• 📊 Real-time animation — Watch latency appear live in alternate screen buffer
• 🏆 Smart ranking — Top 3 fastest models highlighted with medals 🥇🥈🥉
• ⏱ Adaptive monitoring — Starts in a fast 2s cadence for 60s, settles to 10s, slows to 30s after 5 minutes idle, and supports a forced 4s mode
• 📈 Rolling averages — Avg calculated from ALL successful pings since start
• 📊 Uptime tracking — Percentage of successful pings shown in real-time
• 📐 Stability score — Composite 0–100 score measuring consistency (p95, jitter, spikes, uptime)
• 📊 Usage tracking — Monitor remaining quota for each exact provider/model pair when the provider exposes it; otherwise the TUI shows a green dot instead of a misleading percentage.
• 📜 Request Log Overlay — Press X to inspect recent proxied requests and token usage for exact provider/model pairs.
• 📋 Changelog Overlay — Press N to browse all versions in an index, then Enter to view details for any version with full scroll support
• 🛠 MODEL_NOT_FOUND Rotation — If a specific provider returns a 404 for a model, the TUI intelligently rotates through other available providers for the same model.
• 🔄 Auto-retry — Timeout models keep getting retried, nothing is ever "given up on"
• 🎮 Interactive selection — Navigate with arrow keys directly in the table, press Enter to act
• 💻 OpenCode integration — Auto-detects NIM setup, sets model as default, launches OpenCode
• 🦞 OpenClaw integration — Sets selected model as default provider in ~/.openclaw/openclaw.json
• 🧰 Public tool launchers — Enter auto-configures and launches 10+ tools: OpenCode CLI, OpenCode Desktop, OpenClaw, Crush, Goose, Aider, Claude Code, Codex, Gemini, Qwen, OpenHands, Amp, and Pi. All tools auto-select the chosen model on launch.
• 🔌 Install Endpoints flow — Press Y to install one configured provider into any of the 13 supported tools, with a choice between Direct Provider (pure API) or FCM Proxy V2 (key rotation + usage tracking), then pick all models or a curated subset
• 📝 Feature Request (J key) — Send anonymous feedback directly to the project team
• 🐛 Bug Report (I key) — Send anonymous bug reports directly to the project team
• 🎨 Clean output — Zero scrollback pollution, interface stays open until Ctrl+C
• 📶 Status indicators — UP ✅ · No Key 🔑 · Timeout ⏳ · Overloaded 🔥 · Not Found 🚫
• 🔍 Keyless latency — Models are pinged even without an API key
• 🏷 Tier filtering — Filter models by tier letter (S, A, B, C)
• ⭐ Persistent favorites — Press F on a selected row to pin/unpin it
• 🙈 Configured-only by default — Press E to toggle showing only providers with configured API keys; the choice persists across sessions and profiles
• 🪟 Width guardrail — If your terminal is too narrow, the TUI shows a centered warning instead of rendering a broken table

📋 Requirements

Before using free-coding-models, make sure you have:

1. Node.js 18+ — Required for native fetch API
2. At least one free API key — pick any or all of:
   • NVIDIA NIM — build.nvidia.com → Profile → API Keys → Generate – free tier: 40 req/min (no credit card)
   • Groq — console.groq.com/keys → Create API Key – free tier: 30‑50 RPM per model (varies)
   • Cerebras — cloud.cerebras.ai → API Keys → Create – free tier: generous (developer tier 10× higher limits)
   • SambaNova — sambanova.ai/developers → Developers portal → API key (dev tier generous)
   • OpenRouter — openrouter.ai/keys → Create key (free requests on :free models, see details below)

OpenRouter Free Tier Details

OpenRouter provides free requests on free models (:free):

──────────────────────────────────────────────────
  OpenRouter — Free requests on free models (:free)
──────────────────────────────────────────────────

  No credits (or <$10)   →   50  requests / day   (20 req/min)
  ≥ $10 in credits      →  1000 requests / day   (20 req/min)

──────────────────────────────────────────────────
Key things to know:

  • Free models (:free) never consume your credits.
    Your $10 stays untouched if you only use :free models.

  • Failed requests still count toward your daily quota.

  • Quota resets every day at midnight UTC.

  • Free-tier popular models may be additionally rate-limited
    by the provider itself during peak hours.
──────────────────────────────────────────────────

• Hugging Face Inference — huggingface.co/settings/tokens → Access Tokens (free monthly credits)
• Replicate — replicate.com/account/api-tokens → Create token – free tier: 6 req/min (no payment) – up to 3,000 RPM (API) / 600 RPM (predictions) with payment
• DeepInfra — deepinfra.com/login → Login → API key – free tier: 200 concurrent requests (default)
• Fireworks AI — fireworks.ai → Settings → Access Tokens – $1 free credits; 10 req/min without payment (full limits with payment)
• Mistral Codestral — codestral.mistral.ai → API Keys (30 req/min, 2000/day — phone required)
• Hyperbolic — app.hyperbolic.ai/settings → API Keys ($1 free trial)
• Scaleway — console.scaleway.com/iam/api-keys → IAM → API Keys (1M free tokens)
• Google AI Studio — aistudio.google.com/apikey → Get API key (free Gemma models, 14.4K req/day)
• SiliconFlow — cloud.siliconflow.cn/account/ak → API Keys (free-model quotas vary by model)
• Together AI — api.together.ai/settings/api-keys → API Keys (credits/promotions vary)
• Cloudflare Workers AI — dash.cloudflare.com → Create API token + set CLOUDFLARE_ACCOUNT_ID (Free: 10k neurons/day)
• Perplexity API — perplexity.ai/settings/api → API Key (tiered limits by spend)
• ZAI — z.ai → Get API key (Coding Plan subscription)

3. OpenCode (optional) — Install OpenCode to use the OpenCode integration
4. OpenClaw (optional) — Install OpenClaw to use the OpenClaw integration

💡 Tip: You don't need all twenty providers. One key is enough to get started. Add more later via the Settings screen (P key). Models without a key still show real latency (🔑 NO KEY) so you can evaluate providers before signing up.

📦 Installation

# npm (global install — recommended)
npm install -g free-coding-models

# pnpm
pnpm add -g free-coding-models

# bun
bun add -g free-coding-models

# Or use directly with npx/pnpx/bunx
npx free-coding-models YOUR_API_KEY
pnpx free-coding-models YOUR_API_KEY
bunx free-coding-models YOUR_API_KEY

🆕 What's New

Version 0.2.6 brings powerful new features:

• --json flag — Output model results as JSON for scripting, CI/CD pipelines, and monitoring dashboards. Perfect for automation: free-coding-models --tier S --json | jq '.[0].modelId'

• Persistent ping cache — Results are cached for 5 minutes between runs. Startup is nearly instant when cache is fresh, and you save API rate limits. Cache file: ~/.free-coding-models.cache.json

• Config security check — Automatically warns if your API key config file has insecure permissions and offers one-click auto-fix with chmod 600

• Provider colors everywhere — Provider names are now colored consistently in logs, settings, and the main table for better visual recognition

🚀 Usage

# Just run it — starts in OpenCode CLI mode, prompts for API key if not set
free-coding-models

# Explicitly target OpenCode CLI (TUI + Enter launches OpenCode CLI)
free-coding-models --opencode

# Explicitly target OpenCode Desktop (TUI + Enter sets model & opens Desktop app)
free-coding-models --opencode-desktop

# Explicitly target OpenClaw (TUI + Enter sets model as default in OpenClaw)
free-coding-models --openclaw

# Launch other supported public tools with the selected model
free-coding-models --crush
free-coding-models --goose

# Show only top-tier models (A+, S, S+)
free-coding-models --best

 # Analyze for 10 seconds and output the most reliable model
 free-coding-models --fiable

 # Output results as JSON (for scripting/automation)
free-coding-models --json
free-coding-models --tier S --json | jq '.[0].modelId'  # Get fastest S-tier model ID
free-coding-models --json | jq '.[] | select(.avgPing < 500)'  # Filter by latency

 # Filter models by tier letter
free-coding-models --tier S          # S+ and S only
free-coding-models --tier A          # A+, A, A- only
free-coding-models --tier B          # B+, B only
free-coding-models --tier C          # C only

# Combine flags freely
free-coding-models --openclaw --tier S
free-coding-models --opencode --best
free-coding-models --tier S --json

Choosing the target tool

Running free-coding-models with no launcher flag starts in OpenCode CLI mode.

• Press Z in the TUI to cycle the public launch targets: OpenCode CLI → OpenCode Desktop → OpenClaw → Crush → Goose → Pi → Aider → Claude Code → Codex → Gemini → Qwen → OpenHands → Amp
• Or start directly in the target mode with a CLI flag such as --opencode-desktop, --openclaw, --crush, --goose, --pi, --aider, --claude-code, --codex, --gemini, --qwen, --openhands, or --amp
• The active target is always visible in the header badge before you press Enter

How it works:

1. Ping phase — All enabled models are pinged in parallel (up to 159 across 20 providers)
2. Continuous monitoring — Models start at 2s re-pings for 60s, then fall back to 10s automatically, and slow to 30s after 5 minutes idle unless you force 4s mode with W
3. Real-time updates — Watch "Latest", "Avg", and "Up%" columns update live
4. Select anytime — Use ↑↓ arrows to navigate, press Enter on a model to act
5. Smart detection — Automatically detects if NVIDIA NIM is configured in OpenCode or OpenClaw

Setup wizard (first run — walks through all 20 providers):

  🔑 First-time setup — API keys
  Enter keys for any provider you want to use. Press Enter to skip one.

  ● NVIDIA NIM
    Free key at: https://build.nvidia.com
    Profile → API Keys → Generate
  Enter key (or Enter to skip): nvapi-xxxx

  ● Groq
    Free key at: https://console.groq.com/keys
    API Keys → Create API Key
  Enter key (or Enter to skip): gsk_xxxx

  ● Cerebras
    Free key at: https://cloud.cerebras.ai
    API Keys → Create
  Enter key (or Enter to skip):

  ● SambaNova
    Free key at: https://cloud.sambanova.ai/apis
    API Keys → Create ($5 free trial, 3 months)
  Enter key (or Enter to skip):

  ✅ 2 key(s) saved to ~/.free-coding-models.json
  You can add or change keys anytime with the P key in the TUI.

You don't need all twenty providers — skip any provider by pressing Enter. At least one key is required.

Adding or changing keys later

Press P to open the Settings screen at any time:

  ⚙  Settings

  Providers

  ❯ [ ✅ ] NVIDIA NIM              nvapi-••••••••••••3f9a  [Test ✅]  Free tier (provider quota by model)
    [ ✅ ] OpenRouter              (no key set)            [Test —]   Free on :free (50/day <$10, 1000/day ≥$10)
    [ ✅ ] Hugging Face Inference  (no key set)            [Test —]   Free monthly credits (~$0.10)

  Setup Instructions — NVIDIA NIM
  1) Create a NVIDIA NIM account: https://build.nvidia.com
  2) Profile → API Keys → Generate
  3) Press T to test your key

  ↑↓ Navigate  •  Enter Edit/Run  •  + Add key  •  - Remove key  •  Space Toggle  •  T Test key  •  S Sync→OpenCode  •  R Restore backup  •  U Updates  •  ⌫ Delete profile  •  Esc Close

• ↑↓ — navigate providers
• Enter — edit the selected key, run maintenance actions, or load the selected profile
• + / - — add another key for the selected provider or remove one
• Space — toggle provider enabled/disabled
• T — fire a real test ping to verify the key works (shows ✅/❌)
• S — sync fcm-proxy into OpenCode when proxy mode + persistence are enabled
• R — restore the last OpenCode backup created by sync/cleanup flows
• U — manually check npm for a newer version
• Backspace — delete the selected saved profile
• Esc — close settings and reload models list

Keys are saved to ~/.free-coding-models.json (permissions 0600).

Manual update is in the same Settings screen (P) under Maintenance (Enter to check, Enter again to install when an update is available). Favorites are also persisted in the same config file and survive restarts. The main table now starts in Configured Only mode, so if nothing is set up yet you can press P and add your first API key immediately.

Environment variable overrides

Env vars always take priority over the config file:

NVIDIA_API_KEY=nvapi-xxx free-coding-models
GROQ_API_KEY=gsk_xxx free-coding-models
CEREBRAS_API_KEY=csk_xxx free-coding-models
OPENROUTER_API_KEY=sk-or-xxx free-coding-models
HUGGINGFACE_API_KEY=hf_xxx free-coding-models
REPLICATE_API_TOKEN=r8_xxx free-coding-models
DEEPINFRA_API_KEY=di_xxx free-coding-models
FIREWORKS_API_KEY=fw_xxx free-coding-models
SILICONFLOW_API_KEY=sk_xxx free-coding-models
TOGETHER_API_KEY=together_xxx free-coding-models
 CLOUDFLARE_API_TOKEN=cf_xxx CLOUDFLARE_ACCOUNT_ID=your_account_id free-coding-models
 PERPLEXITY_API_KEY=pplx_xxx free-coding-models
 ZAI_API_KEY=zai-xxx free-coding-models
 DASHSCOPE_API_KEY=sk-xxx free-coding-models

Get your free API keys

NVIDIA NIM (44 models, S+ → C tier):

1. Sign up at build.nvidia.com
2. Go to Profile → API Keys → Generate API Key
3. Name it (e.g. "free-coding-models"), set expiry to "Never"
4. Copy — shown only once!

Groq (6 models, fast inference):

1. Sign up at console.groq.com
2. Go to API Keys → Create API Key

Cerebras (3 models, ultra-fast silicon):

1. Sign up at cloud.cerebras.ai
2. Go to API Keys → Create

OpenRouter (:free models):

1. Sign up at openrouter.ai/keys
2. Create API key (sk-or-...)

Hugging Face Inference:

1. Sign up at huggingface.co/settings/tokens
2. Create Access Token (hf_...)

Replicate:

1. Sign up at replicate.com/account/api-tokens
2. Create API token (r8_...)

DeepInfra:

1. Sign up at deepinfra.com/login
2. Create API key from your account dashboard

Fireworks AI:

1. Sign up at fireworks.ai
2. Open Settings → Access Tokens and create a token

Mistral Codestral:

1. Sign up at codestral.mistral.ai
2. Go to API Keys → Create

Hyperbolic:

1. Sign up at app.hyperbolic.ai/settings
2. Create an API key in Settings

Scaleway:

1. Sign up at console.scaleway.com/iam/api-keys
2. Go to IAM → API Keys

Google AI Studio:

1. Sign up at aistudio.google.com/apikey
2. Create an API key for Gemini/Gemma endpoints

SiliconFlow:

1. Sign up at cloud.siliconflow.cn/account/ak
2. Create API key in Account → API Keys

Together AI:

1. Sign up at api.together.ai/settings/api-keys
2. Create an API key in Settings

Cloudflare Workers AI:

1. Sign up at dash.cloudflare.com
2. Create an API token with Workers AI permissions
3. Export both CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID

Perplexity API:

1. Sign up at perplexity.ai/settings/api
2. Create API key (PERPLEXITY_API_KEY)

Alibaba Cloud (DashScope) (8 models, Qwen3-Coder family):

1. Sign up at modelstudio.console.alibabacloud.com
2. Activate Model Studio (1M free tokens per model, Singapore region, 90 days)
3. Create API key (DASHSCOPE_API_KEY)

ZAI (5 models, GLM family):

1. Sign up at z.ai
2. Subscribe to Coding Plan
3. Get API key from dashboard

💡 Free tiers — each provider exposes a dev/free tier with its own quotas. ZAI requires a Coding Plan subscription.

🤖 Coding Models

159 coding models across 20 providers and 8 tiers, ranked by SWE-bench Verified — the industry-standard benchmark measuring real GitHub issue resolution. Scores are self-reported by providers unless noted.

Alibaba Cloud (DashScope) (8 models)

ZAI Coding Plan (5 models)

NVIDIA NIM (44 models)

Groq (10 models)

Cerebras (7 models)

Tier scale

• S+/S — Elite frontier coders (≥60% SWE-bench), best for complex real-world tasks and refactors
• A+/A — Great alternatives, strong at most coding tasks
• A-/B+ — Solid performers, good for targeted programming tasks
• B/C — Lightweight or older models, good for code completion on constrained infra

Filtering by tier

Use --tier to focus on a specific capability band:

free-coding-models --tier S     # Only S+ and S (frontier models)
free-coding-models --tier A     # Only A+, A, A- (solid performers)
free-coding-models --tier B     # Only B+, B (lightweight options)
free-coding-models --tier C     # Only C (edge/minimal models)

📊 TUI Columns

The main table displays one row per model with the following columns:

Verdict values

The Verdict column combines average latency with stability analysis:

📐 Stability Score

The Stability column (sort with B key) shows a composite 0–100 score that answers: "How consistent and predictable is this model?"

Average latency alone is misleading — a model averaging 250ms that randomly spikes to 6 seconds feels slower in practice than a steady 400ms model. The stability score captures this.

Formula

Four signals are normalized to 0–100 each, then combined with weights:

Stability = 0.30 × p95_score
          + 0.30 × jitter_score
          + 0.20 × spike_score
          + 0.20 × reliability_score

📡 FCM Proxy V2

free-coding-models includes a local reverse proxy that merges all your provider API keys into one endpoint. Optional background service mode keeps it running 24/7 — even without the TUI.

Disabled by default — enable in Settings (P) → FCM Proxy V2 settings.

What the proxy does

In-process vs Background Service mode

Quick setup

Via TUI (recommended):

1. Press P to open Settings
2. Select FCM Proxy V2 settings → and press Enter
3. Enable Proxy mode, then select Install background service

Via CLI:

free-coding-models daemon install     # Install + start as OS service
free-coding-models daemon status      # Check running status
free-coding-models daemon restart     # Restart after config changes
free-coding-models daemon stop        # Graceful stop (SIGTERM)
free-coding-models daemon uninstall   # Remove OS service completely
free-coding-models daemon logs        # Show recent service logs

Service management

The dedicated FCM Proxy V2 overlay (accessible via J from main TUI, or Settings → Enter) provides full control:

• Active tool selector — Choose which AI coding tool receives proxy config (cycles through all 12 syncable tools)
• Auto-sync toggle — Automatically write the fcm-proxy provider to the active tool's config when the proxy starts
• Cleanup — Remove fcm-proxy entries from the active tool's config (works for any syncable tool)
• Status display — Running/Stopped/Stale/Unhealthy with PID, port, uptime, account/model counts
• Version mismatch detection — warns if service version differs from installed FCM version
• Restart — stop + start via the OS service manager
• Stop — graceful SIGTERM (service may auto-restart if installed)
• Force kill — emergency SIGKILL for stuck processes
• View logs — last 50 lines from ~/.free-coding-models/daemon-stdout.log

Platform support

Config files

The proxy.activeTool field in the config file tracks which tool the proxy auto-syncs to (e.g. "opencode", "aider", "claude-code").

Cleanup

• From the FCM Proxy V2 overlay: Clean {tool} proxy config — removes fcm-proxy entries from whichever tool is currently selected
• Or: free-coding-models --clean-proxy

Safety

• Dev guard: installDaemon() is blocked when running from a git checkout — prevents hardcoding local repo paths in OS service files
• Localhost only: The proxy listens on 127.0.0.1, never exposed to the network
• Consent required: Service installation requires explicit user action — never auto-installs
• Hot-reload: Config changes are picked up automatically without restarting the service

📜 Request Log Overlay

Press X at any time to open the dedicated request-log overlay.

• Proxy-only accounting: Entries are written when requests flow through the multi-account proxy.
• Exact token totals: The overlay aggregates prompt+completion usage per proxied request.
• Per-request visibility: You can inspect provider, model, status, token count, and latency for recent requests.
• Startup table reuse: The Used column in the main table is derived from the same request log file.

Use ↑↓ to scroll and Esc or X to return to the main table.

🧰 Supported Tool Launchers

You can use free-coding-models with 12+ AI coding tools. When you select a model and press Enter, the tool automatically configures and pre-selects your chosen model:

Press Z to cycle through all 13 tool modes in the TUI, or use flags to start in your preferred mode.

⚡ = Requires FCM Proxy V2 background service (press J to enable). These tools cannot connect to free providers without the proxy.

All tools are also available as install targets in the Install Endpoints flow (Y key) — install an entire provider catalog into any tool with one flow, choosing between Direct Provider or FCM Proxy V2 connection.

🔌 OpenCode Integration

The easiest way — let free-coding-models do everything:

1. Run: free-coding-models --opencode (or launch with no flag to use the default OpenCode CLI mode)
2. Wait for models to be pinged (green ✅ status)
3. Navigate with ↑↓ arrows to your preferred model
4. Press Enter — tool automatically:
   • Detects if NVIDIA NIM is configured in OpenCode
   • Sets your selected model as default in ~/.config/opencode/opencode.json
   • Launches OpenCode with the model pre-selected and ready to use

tmux sub-agent panes

When launched from an existing tmux session, free-coding-models now auto-adds an OpenCode --port argument so OpenCode/oh-my-opencode can spawn sub-agents in panes.

• Priority 1: reuse OPENCODE_PORT if it is valid and free
• Priority 2: auto-pick the first free port in 4096-5095

You can force a specific port:

OPENCODE_PORT=4098 free-coding-models --opencode

ZAI provider proxy

OpenCode doesn't natively support ZAI's API path format (/api/coding/paas/v4/*). When you select a ZAI model, free-coding-models automatically starts a local reverse proxy that translates OpenCode's standard /v1/* requests to ZAI's API. This is fully transparent -- just select a ZAI model and press Enter.

How it works:

1. A localhost HTTP proxy starts on a random available port
2. OpenCode is configured with a zai provider pointing at http://localhost:<port>/v1
3. The proxy rewrites /v1/models to /api/coding/paas/v4/models and /v1/chat/completions to /api/coding/paas/v4/chat/completions
4. When OpenCode exits, the proxy shuts down automatically

No manual configuration needed -- the proxy lifecycle is managed entirely by free-coding-models.

Manual OpenCode Setup (Optional)

Create or edit ~/.config/opencode/opencode.json:

{
  "provider": {
    "nvidia": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "NVIDIA NIM",
      "options": {
        "baseURL": "https://integrate.api.nvidia.com/v1",
        "apiKey": "{env:NVIDIA_API_KEY}"
      }
    }
  },
  "model": "nvidia/deepseek-ai/deepseek-v3.2"
}

Then set the environment variable:

export NVIDIA_API_KEY=nvapi-xxxx-your-key-here
# Add to ~/.bashrc or ~/.zshrc for persistence

Run /models in OpenCode and select NVIDIA NIM provider and your chosen model.

⚠️ Note: Free models have usage limits based on NVIDIA's tier — check build.nvidia.com for quotas.

Automatic Installation Fallback

If NVIDIA NIM is not yet configured in OpenCode, the tool:

• Shows installation instructions in your terminal
• Creates a prompt file in $HOME/prompt with the exact configuration
• Launches OpenCode, which will detect and display the prompt automatically

🦞 OpenClaw Integration

OpenClaw is an autonomous AI agent daemon. free-coding-models can configure it to use NVIDIA NIM models as its default provider — no download or local setup needed, everything runs via the NIM remote API.

Quick Start

free-coding-models --openclaw

Or press Z in the TUI until the header shows OpenClaw, then press Enter on a model.

1. Wait for models to be pinged
2. Navigate with ↑↓ arrows to your preferred model
3. Press Enter — tool automatically:
   • Reads ~/.openclaw/openclaw.json
   • Adds the nvidia provider block (NIM base URL + your API key) if missing
   • Sets agents.defaults.model.primary to nvidia/<model-id>
   • Saves config and prints next steps

What gets written to OpenClaw config

{
  "models": {
    "providers": {
      "nvidia": {
        "baseUrl": "https://integrate.api.nvidia.com/v1",
        "api": "openai-completions"
      }
    }
  },
  "env": {
    "NVIDIA_API_KEY": "nvapi-xxxx-your-key"
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "nvidia/deepseek-ai/deepseek-v3.2"
      },
      "models": {
        "nvidia/deepseek-ai/deepseek-v3.2": {}
      }
    }
  }
}

⚠️ Note: providers must be nested under models.providers — not at the config root. A root-level providers key is ignored by OpenClaw.

⚠️ Note: The model must also be listed in agents.defaults.models (the allowlist). Without this entry, OpenClaw rejects the model with "not allowed" even if it is set as primary.

After updating OpenClaw config

OpenClaw's gateway auto-reloads config file changes (depending on gateway.reload.mode). To apply manually:

# Apply via CLI
openclaw models set nvidia/deepseek-ai/deepseek-v3.2

# Or re-run the interactive setup wizard
openclaw configure

⚠️ Note: openclaw restart does not exist as a CLI command. Kill and relaunch the process manually if you need a full restart.

💡 Why use remote NIM models with OpenClaw? NVIDIA NIM serves models via a fast API — no local GPU required, no VRAM limits, free credits for developers. You get frontier-class coding models (DeepSeek V3, Kimi K2, Qwen3 Coder) without downloading anything.

Patching OpenClaw for full NVIDIA model support

Problem: By default, OpenClaw only allows a few specific NVIDIA models in its allowlist. If you try to use a model that's not in the list, you'll get this error:

Model "nvidia/mistralai/devstral-2-123b-instruct-2512" is not allowed. Use /models to list providers, or /models <provider> to list models.

Solution: Patch OpenClaw's configuration to add ALL 47 NVIDIA models from free-coding-models to the allowlist:

# From the free-coding-models package directory
node patch-openclaw.js

This script:

• Backs up ~/.openclaw/agents/main/agent/models.json and ~/.openclaw/openclaw.json
• Adds all 47 NVIDIA models with proper context window and token limits
• Preserves existing models and configuration
• Prints a summary of what was added

After patching:

1. Restart OpenClaw gateway:

   systemctl --user restart openclaw-gateway

2. Verify models are available:

   free-coding-models --openclaw

3. Select any model — no more "not allowed" errors!

Why this is needed: OpenClaw uses a strict allowlist system to prevent typos and invalid models. The patch-openclaw.js script populates the allowlist with all known working NVIDIA models, so you can freely switch between them without manually editing config files.

⚙️ How it works

┌──────────────────────────────────────────────────────────────────┐
│  1. Enter alternate screen buffer (like vim/htop/less)           │
│  2. Ping ALL models in parallel                                  │
│  3. Display real-time table with Latest/Avg/Stability/Up%        │
│  4. Re-ping ALL models at 2s on startup, then 10s steady-state │
│     and 30s after 5m idle unless forced back to 4s with W      │
│  5. Update rolling averages + stability scores per model        │
│  6. User can navigate with ↑↓ and select with Enter            │
│  7. On Enter (OpenCode): set model, launch OpenCode             │
│  8. On Enter (OpenClaw): update ~/.openclaw/openclaw.json       │
└──────────────────────────────────────────────────────────────────┘

Result: Continuous monitoring interface that stays open until you select a model or press Ctrl+C. Rolling averages give you accurate long-term latency data, the stability score reveals which models are truly consistent vs. deceptively spikey, and you can configure your tool of choice with one keystroke. If the terminal is too narrow, the app shows a centered warning instead of a truncated table.

📋 API Reference

Environment variables (override config file):

Config file: ~/.free-coding-models.json (created automatically, permissions 0600)

{
  "apiKeys": {
    "nvidia":   "nvapi-xxx",
    "groq":     "gsk_xxx",
    "cerebras": "csk_xxx",
    "openrouter": "sk-or-xxx",
    "huggingface": "hf_xxx",
    "replicate": "r8_xxx",
    "deepinfra": "di_xxx",
    "siliconflow": "sk_xxx",
    "together": "together_xxx",
    "cloudflare": "cf_xxx",
    "perplexity": "pplx_xxx",
    "zai":      "zai-xxx"
  },
  "providers": {
    "nvidia":   { "enabled": true },
    "groq":     { "enabled": true },
    "cerebras": { "enabled": true },
    "openrouter": { "enabled": true },
    "huggingface": { "enabled": true },
    "replicate": { "enabled": true },
    "deepinfra": { "enabled": true },
    "siliconflow": { "enabled": true },
    "together": { "enabled": true },
    "cloudflare": { "enabled": true },
    "perplexity": { "enabled": true },
    "zai":      { "enabled": true }
   },
   "settings": {
     "hideUnconfiguredModels": true
   },
   "favorites": [
     "nvidia/deepseek-ai/deepseek-v3.2"
   ]
 }

Configuration:

• Ping timeout: 15 seconds per attempt (slow models get more time)
• Ping cadence: startup burst at 2 seconds for 60s, then 10 seconds normally, 30 seconds when idle for 5 minutes, or forced 4 seconds via W
• Monitor mode: Interface stays open forever, press Ctrl+C to exit

Flags:

Keyboard shortcuts (main TUI):

• ↑↓ — Navigate models
• Enter — Select model and launch the current target tool from the header badge
• R/S/C/M/O/L/A/H/V/B/U/G — Sort by Rank/SWE/Ctx/Model/Provider/Latest/Avg/Health/Verdict/Stability/Up%/Usage
• F — Toggle favorite on selected model (⭐ in Model column, pinned at top)
• T — Cycle tier filter (All → S+ → S → A+ → A → A- → B+ → B → C → All)
• D — Cycle provider filter (All → NIM → Groq → ...)
• E — Toggle configured-only mode (on by default, persisted across sessions and profiles)
• Z — Cycle target tool (OpenCode CLI → Desktop → OpenClaw → Crush → Goose → Pi → Aider → Claude Code → Codex → Gemini → Qwen → OpenHands → Amp)
• X — Toggle request logs (recent proxied request/token usage logs, up to 500 entries)
• A (in logs) — Toggle between showing 500 entries or ALL logs
• P — Open Settings (manage API keys, toggles, updates, profiles)
• Y — Open Install Endpoints (provider → tool → connection mode → scope → models, Direct or FCM Proxy V2)
• Shift+P — Cycle through saved profiles (switches live TUI settings)
• Shift+S — Save current TUI settings as a named profile (inline prompt)
• Q — Open Smart Recommend overlay (find the best model for your task)
• N — Open Changelog overlay (browse index of all versions, Enter to view details, B to go back)
• W — Cycle ping mode (FAST 2s → NORMAL 10s → SLOW 30s → FORCED 4s)
• J — Open FCM Proxy V2 settings (shows green "Proxy On" / red "Proxy Off" badge in footer)
• I — Feedback, bugs & requests
• K / Esc — Show help overlay / Close overlay
• Ctrl+C — Exit

Pressing K now shows a full in-app reference: main hotkeys, settings hotkeys, and CLI flags with usage examples.

🔌 Install Endpoints (Y)

Y opens a dedicated install flow for configured providers. The 5-step flow is:

1. Provider — Pick one provider that already has an API key in Settings
2. Tool — Pick the target tool from all 13 supported tools:
   • Config-based: OpenCode CLI, OpenCode Desktop, OpenClaw, Crush, Goose, Pi, Aider, Amp, Gemini, Qwen
   • Env-file based: Claude Code, Codex CLI, OpenHands (writes ~/.fcm-{tool}-env — source it before launching)
3. Connection Mode — Choose how the tool connects to the provider:
   • ⚡ Direct Provider — pure API connection, no proxy involved
   • 🔄 FCM Proxy V2 — route through FCM Proxy V2 with key rotation and usage tracking
4. Scope — Choose Install all models or Install selected models only
5. Models (if scope = selected) — Multi-select individual models from the provider catalog

Important behavior:

• Installs are written into the target tool config as FCM-managed entries (namespaced under fcm-*)
• Install all models is the recommended path because FCM can refresh that catalog automatically on later launches when the provider model list changes
• Install selected models only is useful when you want a smaller curated picker inside the target tool
• OpenCode CLI and OpenCode Desktop share the same opencode.json, so the managed provider appears in both
• For env-based tools (Claude Code, Codex, OpenHands), FCM writes a sourceable file at ~/.fcm-{tool}-env — run source ~/.fcm-claude-code-env before launching

Keyboard shortcuts (Settings screen — P key):

• ↑↓ — Navigate providers, maintenance row, and profile rows
• Enter — Edit API key inline, check/install update, or load a profile
• Space — Toggle provider enabled/disabled
• T — Test current provider's API key (fires a live ping)
• U — Check for updates manually from settings
• Backspace — Delete the selected profile (only on profile rows)
• Esc — Close settings and return to main TUI

📋 Config Profiles

Profiles let you save and restore different TUI configurations — useful if you switch between work/personal setups, different tier preferences, or want to keep separate favorites lists.

What's stored in a profile:

• Favorites (starred models)
• Sort column and direction
• Tier filter
• Ping mode
• Configured-only filter
• API keys

Saving a profile:

1. Configure the TUI the way you want (favorites, sort, tier, etc.)
2. Press Shift+S — an inline prompt appears at the bottom
3. Type a name (e.g. work, fast-only, presentation) and press Enter
4. The profile is saved and becomes the active profile (shown as a purple badge in the header)

Switching profiles:

• Shift+P in the main table — cycles through saved profiles (or back to raw config)
• --profile <name> — load a specific profile on startup

Managing profiles:

• Open Settings (P key) — scroll down to the Profiles section
• Enter on a profile row to load it
• Backspace on a profile row to delete it

Profiles are stored inside ~/.free-coding-models.json under the profiles key.

🔧 Development

git clone https://github.com/vava-nessa/free-coding-models
cd free-coding-models
npm install
npm start -- YOUR_API_KEY

Releasing a new version

1. Make your changes and commit them with a descriptive message
2. Update CHANGELOG.md with the new version entry
3. Bump "version" in package.json (e.g. 0.1.3 → 0.1.4)
4. Commit with just the version number as the message:

git add .
git commit -m "0.1.4"
git push

The GitHub Actions workflow automatically publishes to npm on every push to main.

📄 License

MIT © vava

_{Built with ☕ and 🌹 by vava}

📬 Contribute

We welcome contributions! Feel free to open issues, submit pull requests, or get involved in the project.

Q: Can I use this with other providers? A: Yes, the tool is designed to be extensible; see the source for examples of customizing endpoints.

Q: How accurate are the latency numbers? A: They represent average round-trip times measured during testing; actual performance may vary based on network conditions.

Q: Do I need to download models locally for OpenClaw? A: No — free-coding-models configures OpenClaw to use NVIDIA NIM's remote API, so models run on NVIDIA's infrastructure. No GPU or local setup required.

📧 Support

For questions or issues, open a GitHub issue.

💬 Let's talk about the project on Discord: https://discord.gg/ZTNFHvvCkU

_{We collect anonymous usage data to improve the tool and fix bugs. No personal information is ever collected.}